putitoutthere 0.2.29 → 0.2.30

package/MIGRATIONS.md

@@ -21,6 +21,1188 @@ Each section covers five things, in order:
 
 ## Unreleased
 
+### `status`: registry-vs-tag drift report
+
+**Summary.** New read-only command `putitoutthere status` reports, per
+package, whether the latest git tag matches the registry's latest
+published version, flagging drift — notably `published, untagged` (a
+version live on the registry but missing its tag, which strands the
+package). Reads public registry metadata only; no auth.
+
+**Required changes.** None. Additive — a new command.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None — new surface.
+
+**Verification.** Run `status` over a repo with a published-but-untagged
+package: that package shows `published, untagged` and `status --check`
+exits non-zero; a fully in-sync repo shows every package `in sync` and
+exits zero. `--json` emits the same rows as JSON.
+
+### reconcile: backfill missing tags
+
+**Summary.** New command `putitoutthere reconcile` backfills the missing
+git tag for every package that is live on its registry but untagged
+(`status`'s `published, untagged` drift). It is the on-demand companion to
+the publish-path auto-heal: auto-heal only fires for a package already in a
+publish run, so a package whose globs never change again stays stuck;
+`reconcile` heals it without a release. It reuses the same `computeStatus`
+detection `status` reports and the same idempotent `ensureTag` the publish
+path heals with — no parallel logic.
+
+**Required changes.** None. Additive — a new command.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** `--dry-run` is now accepted on
+`reconcile` (it previews the heal without writing). It remains rejected on
+`plan` / `publish`, unchanged from the #244 removal.
+
+**Verification.** On a repo with a published-but-untagged package, run
+`putitoutthere reconcile`: the missing tag is created (per the package's
+`tag_format`) — pointed at a sibling package's tag commit for that version
+when one exists, else `HEAD` — and pushed; `git tag` / GitHub show it, and
+`status` then reports the package `in sync`. A second `reconcile` run is a
+no-op. `reconcile --dry-run` reports what it would create without writing;
+`--json` emits the actions.
+
+### publish-path auto-heal: missing tags
+
+**Summary.** `putitoutthere publish` now self-heals a missing git tag: when
+a version is already live on the registry but has no tag, publish writes the
+tag instead of skipping silently. Previously the already-published branch
+returned before tagging, so a version that reached the registry on a
+half-failed run (published, then the run died before the tag step) was
+stranded published-but-untagged — and because piot derives "last released"
+from tags, it skipped forever and could never bump, while dependents drifted
+ahead into unflagged version skew.
+
+**Required changes.** None. Purely additive behavior on the publish path.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** On the next release run after
+upgrading, any package that is live on a registry but missing its tag has the
+tag created (and pushed) at the release commit, automatically. Idempotent:
+packages already correctly tagged are untouched.
+
+**Verification.** Re-run a release on a repo with a published-but-untagged
+package: the run now creates the missing tag (per the package's `tag_format`;
+visible via `git tag` / on GitHub) and the package resumes normal version
+bumping on later releases.
+
+### pypi version-independent wheels build once
+
+**Summary.** A `kind = "pypi"` `build = "maturin"` package whose wheel is
+Python-version-independent — `[tool.maturin].bindings = "bin"` (a
+Rust-binary `py3-none` wheel) or a pyo3 `abi3` / `abi3-pyXY` extension (a
+`cp3x-abi3` stable-ABI wheel) — used to be built once per CPython version
+in the resolved set (inferred from `[project].requires-python`, or pinned
+via `python_versions`). Because such a wheel is byte-identical no matter
+which interpreter built it, the fan produced N duplicate wheels, and the
+documented `pypi-publish` recipe's `merge-multiple: true` download then
+race-corrupted the identical wheel filenames extracted onto one path
+(`twine check` → `zipfile.BadZipFile`). The planner now collapses the fan
+to a single wheel per target for these packages.
+
+**Required changes.** None. Detection is automatic from your existing
+`pyproject.toml` / `Cargo.toml`; no `putitoutthere.toml`, `release:`
+trailer, or reusable-workflow input changes. The consumer `pypi-publish`
+job is unchanged — its `pattern: '*-wheel-*'` still matches the (now
+single) wheel artifact.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** For a version-independent
+maturin wheel resolving to more than one CPython version:
+
+| | Before | After |
+|---|--------|-------|
+| Wheel build rows per target | one per resolved version (e.g. 6 for `>=3.9`) | one |
+| Wheel artifact name | `<pkg>-wheel-<triple>-py<ver>` (per version) | `<pkg>-wheel-<triple>` (unsuffixed) |
+| Build interpreter | each resolved version | newest resolved version only |
+
+Ordinary per-version extension modules (no abi3, no `bindings = "bin"`)
+are unaffected — they still fan and keep their `-py<ver>` suffixes. The
+sdist row is unchanged. Detection is conservative: an abi3 setup the
+engine doesn't recognize (a workspace-inherited `pyo3` dependency, a
+`[target.'cfg(...)'.dependencies]` table) falls back to the prior fanning
+behavior.
+
+**Verification.** Run `putitoutthere plan` (or release) a maturin package
+with `bindings = "bin"` or a pyo3 `abi3` feature and a `requires-python`
+spanning multiple minors. The build matrix now shows a single
+`<pkg>-wheel-<triple>` artifact per target instead of one per version, and
+the `pypi-publish` job's `twine check` no longer fails with `BadZipFile`.
+
+### npm `TLOG_CREATE_ENTRY_ERROR` (409) provenance retry race
+
+**Summary.** `kind = "npm"` releases that publish with provenance
+(`--provenance`, the OIDC trusted-publisher path) could abort mid-matrix
+when npm's internal retry-on-transient-network-error re-submitted a
+byte-identical attestation and Sigstore/Rekor rejected the duplicate with
+`TLOG_CREATE_ENTRY_ERROR` (HTTP 409, "an equivalent entry already exists in
+the transparency log"). Only the registry-PUT edition of that race (the
+`E403` "cannot publish over the previously published versions" shape) was
+tolerated; the attestation edition fell through to a hard failure, which
+for a multi-platform (`napi` / `bundled-cli`) package left the remaining
+sub-packages and the main package unpublished — a partial release. The
+engine now recognizes the 409 and, because a 409 from Rekor does not by
+itself prove the artifact reached the registry, re-probes `npm view` to
+decide: present ⇒ benign duplicate (success); absent ⇒ a genuine partial
+publish, reported as an actionable error.
+
+**Required changes.** None. The behavior is automatic and applies to every
+`kind = "npm"` package; no `putitoutthere.toml`, `release:` trailer, or
+reusable-workflow input changes.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** A `kind = "npm"` publish that
+hits `TLOG_CREATE_ENTRY_ERROR` (409) no longer fails unconditionally:
+
+| Situation | Before | After |
+|-----------|--------|-------|
+| 409 raised, package **is** on the registry | publish job fails (`npm publish (platform) failed: …`) | treated as `already-published` / counted as published; the cascade continues |
+| 409 raised, package is **absent** from the registry | publish job fails with a bare npm stderr dump | publish job still fails, but with an actionable message: re-run the release to mint a fresh attestation |
+
+In the genuine partial-publish case the engine cannot recover in-process —
+an orphaned attestation needs a new `runID`/attempt to produce a fresh
+Rekor entry — so re-running the release is the documented remedy.
+
+**Verification.** Re-run a release whose previous attempt died on
+`TLOG_CREATE_ENTRY_ERROR`. If the sub-package already landed, the run now
+reports it as already-published and proceeds to the remaining packages
+instead of aborting; if it never landed, the error names the package and
+tells you to re-run (which mints a new attestation and gets past the
+dedupe).
+
+### Bundled-CLI launcher generation no-ops without `[package.bundle_cli]`
+
+**Summary.** #299 moved npm bundled-cli launcher generation into the
+engine and invoked it on every bundled-cli package's main row.
+`writeLauncherFromConfig` assumed `[package.bundle_cli]` was always
+present and dereferenced `bundle_cli.bin` unconditionally, so a
+bundled-cli npm package that omits the table — the legacy
+"bring-your-own `scripts/build.cjs` + hand-authored `bin/<bin>.js`"
+shape that #298 explicitly kept opt-in — crashed the release at the
+`write-launcher` step with `Cannot read properties of undefined
+(reading 'bin')`. Launcher generation now no-ops when the table is
+absent, mirroring the cross-compile step's existing `matrix.bundle_cli`
+gate. The gate lives in the engine, not the workflow `if:`, because the
+main row the step runs on never carries `bundle_cli` (`plan.ts` attaches
+it only to per-target bundled-cli rows).
+
+**Required changes.** None. A bundled-cli package that declares
+`[package.bundle_cli]` is unchanged — the engine still generates
+`bin/<bin>.js` and the `package.json#bin` entry. A package that omits
+the table and ships its own launcher (the legacy path) no longer crashes;
+the engine leaves its launcher alone. A consumer that *intended* the
+declarative path and simply forgot the table should add it — the
+cross-compile and launcher generation both key off it:
+
+| Before | After |
+|--------|-------|
+| `build = "bundled-cli"`, `targets = [...]`, no `[package.bundle_cli]` → `write-launcher` TypeError | release succeeds; add `[package.bundle_cli]` with at least `bin` to opt into engine cross-compile + launcher generation |
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** A bundled-cli npm package
+without `[package.bundle_cli]` previously failed its release at the
+`write-launcher` step (as of #299); it now completes, with the engine
+authoring no launcher for it.
+
+**Verification.** Trigger a release for a bundled-cli npm package that
+omits `[package.bundle_cli]`: the run completes (previously it failed at
+the `write-launcher` step). A package that declares the table still gets
+its engine-generated launcher.
+
+### Preflight npm package name must match configured name
+
+**Summary.** Preflight gains `requirePackageJsonShape`, the npm analogue
+of `requirePyprojectShape` / `requireCargoShape` (#301). Every cascaded
+`kind = "npm"` package's `package.json` `name` must equal the configured
+`[[package]].name` (or the `npm` override). `npm publish` packs the
+manifest `name`, but the engine's idempotency probe (`npm view <name>`)
+and the tag / release-URL bookkeeping use the configured name — so a
+divergence silently breaks idempotency and can publish under an
+unexpected name. pypi and crates already enforced the equivalent
+(`PIOT_PYPI_NAME_MISMATCH`, `PIOT_CRATES_NAME_MISMATCH`); this closes the
+gap for npm. The check fires at publish time alongside the existing
+`require*` family and at PR time via `check.yml`. Findings aggregate
+across every failing package.
+
+**Required changes.** None for well-formed manifests — `package.json`
+`name` already matches the configured name in the common case. The repos
+that trip the new check are those that used a path-style identifier as
+`[[package]].name` (e.g. `js/foo`) without setting the `npm` override
+while shipping `package.json` `name = "foo"`; those previously published
+with a broken `npm view` idempotency check and a wrong reported URL, and
+now get a fast preflight red instead. Fix by aligning the names or
+declaring the override:
+
+| Before | After |
+|--------|-------|
+| `name = "js/foo"` (no `npm` override), `package.json` `name = "foo"` | add `npm = "foo"` to the `[[package]]` entry (or rename one side so the two agree) |
+
+The new error code:
+
+| Code | Fires when |
+|------|------------|
+| `PIOT_NPM_NAME_MISMATCH` | `package.json`'s `name` differs from `[[package]].name` (or the `npm` override). |
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** An npm package with a name
+divergence that previously published (under the manifest name, with a
+broken `npm view` idempotency check and a wrong reported URL) now fails
+at preflight with a fingerprintable `PIOT_NPM_NAME_MISMATCH` before any
+side effect. Scoped names are compared verbatim (`npm = "@scope/foo"`
+matches `package.json` `name = "@scope/foo"`). A missing or malformed
+`package.json` is left to the other checks / the publish step.
+
+**Verification.** Set an npm package's `package.json` `name` to something
+other than its configured `[[package]].name` (with no `npm` override),
+run `pnpm putitoutthere check` (or open a PR with `check.yml` wired), and
+see `PIOT_NPM_NAME_MISMATCH` surface in seconds instead of mid-release.
+
+### `_matrix.yml` build job primes a cargo cache (#391)
+
+**Summary.** `_matrix.yml`'s build job previously ran every per-target
+matrix cell without any Cargo cache. Each cell cold-compiled the full
+Rust dep graph on every PR — even PRs that touched nothing Rust-side —
+because `~/.cargo/registry` and the per-package `target/` dir started
+empty on every runner. On a wide bundle_cli / napi / maturin matrix
+this dominated wall-clock: 4-6 min per cell, ~8 min end-to-end on a
+typical downstream consumer's `release-precheck.yml` run, with no
+headroom against a 10-min PR CI gate.
+
+The build job now runs `Swatinem/rust-cache@v2` immediately after
+`actions/checkout`, gated on rows that actually invoke cargo:
+
+- `pypi/maturin` non-sdist (maturin shells out to cargo)
+- `npm/napi` (the consumer's `napi build` script calls cargo)
+- `npm/bundled-cli` non-main (the engine's `cargo build` for the
+  staged CLI binary)
+
+The cache is partitioned by `matrix.target` via `shared-key` so a
+write to one target's slot doesn't blow away the next cell's, and
+`workspaces` enumerates both `matrix.path` (the consumer's package
+crate, where maturin / napi / single-crate bundled-cli compile) and
+`matrix.bundle_cli.crate_path` (the bundle_cli crate when it lives
+in a separate dir from `matrix.path` — the dirsql shape). Rows that
+produce no cargo work (pypi sdist, pure-Python hatch wheels, npm
+vanilla, bundled-cli `main`) skip the cache step entirely.
+
+**Required changes.** None — the cache is internal to the reusable
+workflow. No consumer config, YAML, or scripts need to change.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Per-target matrix cells
+that ran cargo cold previously will now restore their dep graph from
+GitHub Actions cache storage on the second and subsequent matching
+runs (matching = same `matrix.target` + same Cargo.lock contents).
+Cache storage accrues against the consumer's repository quota — the
+same accounting as any other `actions/cache` consumer, no separate
+billing. First run after a `Cargo.lock` change recompiles cold and
+takes the same wall-clock as before. The acceptance criterion: a
+second matrix run with no `Cargo.lock` change finishes the Rust
+compile step in well under one minute per cell.
+
+**Verification.** A `build.yml` (or `release.yml`) run's logs now
+show a `cargo cache (#391)` step between `Set up job` and the first
+Rust-touching step, on every row that invokes cargo. The step logs
+either `Cache hit` (subsequent run, no `Cargo.lock` change) or
+`Cache not found` (first run, or after a `Cargo.lock` change) and
+records a `~/.cargo` + `target/` save at job end. Pure-Python sdist
+and npm vanilla rows do not show the step at all.
+
+### npm bundled-cli: npm-flavor triples now mapped to Rust triples
+
+**Summary.** The `bundle_cli — add Rust target`, `cargo build`, and `stage binary` steps in both `_matrix.yml` and `e2e-fixture-job.yml` previously applied `${TARGET//-linux-gnu/-linux-musl}` directly to `matrix.target`. For `kind = "pypi"` rows `matrix.target` is already a Rust triple (`x86_64-unknown-linux-gnu`), so the substitution worked. For `kind = "npm"` `build = "bundled-cli"` rows `matrix.target` is an napi-rs-flavor triple (`linux-x64-gnu`, `darwin-arm64`, `win32-x64-msvc`, …); the substring `-linux-gnu` does not appear in any of these, so the substitution was a no-op and `rustup target add` received the raw npm triple and failed:
+
+```
+error: toolchain 'stable-x86_64-unknown-linux-gnu' does not support target 'linux-x64-gnu'
+```
+
+Each affected step now contains an explicit `case` statement mapping napi-rs npm triples to their Rust equivalents before the `gnu→musl` swap.
+
+**Required changes.** None — the mapping is inside the reusable workflow. No consumer config, YAML, or scripts need to change.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** `bundle_cli — add Rust target` now calls `rustup target add x86_64-unknown-linux-musl` (etc.) and succeeds. `cargo build --target` and the `stage binary` path-derivation use the correct Rust triple throughout.
+
+**Verification.** A `bundle_cli` npm build job now shows `bundle_cli — add Rust target` completing without error, `bundle_cli — cargo build for linux-x64-gnu` compiling to `x86_64-unknown-linux-musl/release/<bin>`, and `bundle_cli — stage binary` logging `staged: target/x86_64-unknown-linux-musl/release/<bin> -> …`.
+
+### `bundle_cli` stage step runs after consumer `npm run build`
+
+**Summary.** The engine's `bundle_cli — stage binary` step previously ran
+**before** `npm run build --if-present`. A consumer build script that also
+runs `cargo build --target $TARGET` (the raw `-linux-gnu` triple) and copies
+the result to `build/<triple>/` would overwrite the engine's musl binary with
+a glibc-linked one; the existence-only verify check passed and the
+dynamically-linked artifact shipped to the registry. The stage step now runs
+**after** `npm run build --if-present` so the engine's statically-linked musl
+binary always wins. The `bundle_cli — verify` step in `_matrix.yml` now also
+asserts static linking (`file`/`ldd` check), mirroring the check already
+present in `e2e-fixture-job.yml`.
+
+**Required changes.** None — this is a pure step-reordering inside the
+reusable workflow. No consumer-side YAML, config, or scripts need to change.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Consumer build scripts that stage
+a binary to `build/<triple>/` as part of `npm run build` will have that binary
+overwritten by the engine's musl binary. This was always the intended behavior;
+the old ordering was a bug. Consumer scripts that only compile TypeScript or
+do non-binary work are unaffected.
+
+**Verification.** A `bundle_cli` Linux build job's logs now show:
+1. `bundle_cli — cargo build for <triple>` (musl build, unchanged)
+2. `npm run build --if-present` (consumer build step)
+3. `bundle_cli — stage binary into build/<triple>` (engine stages musl binary)
+4. `bundle_cli — verify … is statically linked` (passes)
+
+### `bundle_cli` musl builds install `musl-tools` C cross-compiler
+
+**Summary.** `rustup target add x86_64-unknown-linux-musl` registers the
+Rust musl target but does not install the C cross-compiler
+(`x86_64-linux-musl-gcc`). Crates that compile C source at build time —
+`libsqlite3-sys` with `features = ["bundled"]`, `openssl-sys` with
+`features = ["vendored"]`, and similar — invoke the C compiler directly
+during `cargo build`; without `musl-gcc` present, the build fails with:
+
+```
+failed to find tool "x86_64-linux-musl-gcc": No such file or directory
+```
+
+The `musl-tools` apt package provides `musl-gcc` and is not pre-installed
+on `ubuntu-latest`. `_matrix.yml` and `e2e-fixture-job.yml` now run
+`sudo apt-get install -y musl-tools` and export `CC_<triple>=musl-gcc` to
+`$GITHUB_ENV` before `cargo build`, gated on Linux targets.
+
+**Required changes.** None — the step is added automatically by the
+reusable workflow.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** CLI crates that compile C
+source and previously had to run a custom `build` script to install
+`musl-tools` may be able to remove that script.
+
+**Verification.** On a bundle_cli Linux build, the workflow now prints
+`sudo apt-get install -y musl-tools` before the `cargo build` step.
+Crates with C deps (e.g. `features = ["bundled"]` on `rusqlite`) compile
+successfully without consumer-side workarounds.
+
+### `bundle_cli` Linux binaries compiled as static musl
+
+**Summary.** `bundle_cli`'s Linux cross-compile step previously ran
+`cargo build --target $TARGET` directly on the GitHub-hosted runner.
+That runner's glibc (currently 2.39 on Ubuntu 24.04) got baked into
+the produced binary as a hard runtime requirement, so any older Linux
+at install time failed with `./bin: /lib/x86_64-linux-gnu/libc.so.6:
+version 'GLIBC_2.39' not found`. The fix derives a `BINARY_TARGET`
+from `matrix.target` by substituting `-linux-gnu*` → `-linux-musl*`
+and uses that for the three workflow steps that touch the binary's
+compile triple. Statically-linked musl binaries have no glibc floor.
+The package's declared target triple (used for npm platform-package
+names, napi builds, wheel tags, artifact names) is unchanged; only
+the binary inside switches compile triple.
+
+**Required changes.** None for the common case — the workflow makes
+the swap automatically. The exception: CLI crates that
+dynamic-link a system C library through default cargo features will
+see a linker error on the first release after upgrade. The static
+musl build cannot satisfy a dynamic link against the host's glibc-world
+libraries. The fix is a one-line `Cargo.toml` change per case:
+
+| Symptom (cargo error mentions) | Fix in your CLI's `Cargo.toml` |
+|--------------------------------|--------------------------------|
+| `openssl-sys`, `libssl.so`, OpenSSL          | Switch to `rustls` (`reqwest = { default-features = false, features = ["rustls-tls"] }`), or pin `openssl = { features = ["vendored"] }` |
+| `git2`, `libgit2`              | `git2 = { features = ["vendored-openssl", "vendored-libgit2"] }` |
+| `libsqlite3-sys`, SQLite       | `rusqlite = { features = ["bundled"] }` (or `libsqlite3-sys = { features = ["bundled"] }`) |
+| `libpq`, Postgres client       | Swap `postgres-native-tls` for `postgres-rustls`, or use `sqlx` with the `rustls` feature |
+| `libmysqlclient`, MySQL client | Same — prefer a pure-Rust client; `mysqlclient-sys` has no clean static path |
+
+The musl build fails loudly at release time when one of these is
+missed — there is no silent broken-binary failure mode. A blocked
+release is the worst outcome.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** The bundled binary inside
+a Linux package built before this release required the build
+runner's glibc (currently 2.39); after this release it has no glibc
+requirement and runs on any Linux ≥ kernel 3.2, including Alpine,
+NixOS in musl mode, scratch containers, and any host whose glibc is
+older than the build runner's. Package identifiers (npm platform-
+package names like `@scope/cli-linux-x64-gnu`, PyPI wheel tags,
+artifact upload names) are unchanged — the substitution applies only
+to the binary's compile triple.
+
+**Verification.** Install a `bundle_cli`-enabled package from any
+pre-Ubuntu-24.04 Linux (Ubuntu 22.04, Debian 12, Amazon Linux 2,
+Alpine) and run the CLI — no `GLIBC_2.x not found` error. On the
+build side, the cargo invocation in CI now prints
+`cargo build --release --target x86_64-unknown-linux-musl ...`
+instead of `-gnu` for Linux rows; `file` on the produced binary
+reports `statically linked` instead of `dynamically linked`.
+
+### pypi `requires-python` includes CPython 3.14
+
+**Summary.** Open-ended `requires-python` inference now expands against
+putitoutthere's checked-in released-CPython list through CPython 3.14.
+This fixes the stale-tail failure mode where `requires-python = ">=3.11"`
+emitted cp311/cp312/cp313 wheels but omitted cp314 after Python 3.14 was
+released.
+
+**Required changes.** None.
+
+| Before | After |
+|--------|-------|
+| `requires-python = ">=3.11"` planned wheels only through cp313. | `requires-python = ">=3.11"` plans cp311, cp312, cp313, and cp314, unless `python_versions` is explicitly set. |
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Consumers with open-ended
+`requires-python` ranges may see an extra cp314 wheel row. Explicit
+`python_versions` overrides are unchanged and still pin the exact wheel
+set.
+
+**Verification.** Push a release for a `kind = "pypi"` package whose
+`pyproject.toml` declares `requires-python = ">=3.11"`; the build matrix
+should include a `python_version: "3.14"` row, and the published PyPI
+release should include a cp314 wheel.
+
+### Manual release via `release_packages`
+
+**Summary.** `release.yml` gained an optional `release_packages`
+`workflow_call` input. When set, it triggers a manual release of an
+explicit list of packages, bypassing change detection entirely. The
+motivating case: putitoutthere ships a release-pipeline bug, the bug is
+fixed, and downstream consumers must re-release the affected packages
+even though their own repos have no new commits since the last tag —
+the change-detected path emits an empty matrix in that state and cannot
+release. The input value is a comma-separated list of
+`name[@<bump|version>]` entries; each entry is a package name optionally
+suffixed with `@<patch|minor|major>` (bump the last tag) or an explicit
+`@<X.Y.Z>` semver (used verbatim). A bare name defaults to a patch bump.
+Only the named packages are planned — no `depends_on` cascade, no
+change-detected packages pulled in.
+
+**Required changes.** None — the input is optional and defaults to
+empty, which leaves the normal change-detected release path unchanged.
+To get a manual-release button, wire the input to a `workflow_dispatch`
+trigger in your caller `release.yml`:
+
+| Before | After |
+|--------|-------|
+| <pre>on:<br>  push: { branches: [main] }<br><br>jobs:<br>  release:<br>    uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0</pre> | <pre>on:<br>  push: { branches: [main] }<br>  workflow_dispatch:<br>    inputs:<br>      release_packages:<br>        description: 'Comma-separated name[@bump\|version] list'<br>        required: true<br><br>jobs:<br>  release:<br>    uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v0<br>    with:<br>      release_packages: ${{ inputs.release_packages }}</pre> |
+
+The push-triggered run passes an empty `release_packages` (the `inputs`
+context is empty outside `workflow_dispatch`), so the normal path keeps
+working.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None. The new behavior is
+gated entirely on the new input being non-empty.
+
+**Verification.** Trigger the workflow from the Actions tab with
+`release_packages` set to a known package (e.g. `lib-core@patch`).
+Confirm the plan job's matrix contains exactly that package and the
+publish job tags and publishes it at the expected version.
+
+### pypi multi-version wheels
+
+**Summary.** `kind = "pypi"` packages now build a wheel for every
+CPython version they support, instead of a single wheel for the
+`python_version` workflow input. The version set is resolved per
+package: an explicit `python_versions` array in `putitoutthere.toml`
+wins; otherwise it is inferred from `[project].requires-python` in the
+package's `pyproject.toml`; otherwise a single default (`3.12`) is
+used. The build matrix fans `maturin` per-target wheel rows across the
+resolved set. This closes the incomplete-coverage bug where a package
+declaring `requires-python = ">=3.10"` shipped a cp312-only wheel and
+failed to install on every other interpreter.
+
+**Required changes.** None for the default path — `requires-python`
+inference is automatic. Optionally pin a subset:
+
+| Before | After |
+|--------|-------|
+| _(no knob; one wheel at `python_version`)_ | `python_versions = ["3.12", "3.13"]` under a `[[package]]` with `kind = "pypi"` |
+
+Consumers whose caller-side `pypi-publish` job collects wheels from the
+downloaded artifacts directory need no change as long as it globs all
+wheel artifacts (the recommended recipe already does); multi-version
+`maturin` wheel artifacts are now named
+`<pkg>-wheel-<triple>-py<ver>` rather than `<pkg>-wheel-<triple>`. A
+single planned version keeps the unsuffixed name.
+
+**Deprecations removed.** None. The `python_version` input on
+`release.yml`, `build.yml`, and `_matrix.yml` is now deprecated — it no
+longer affects pypi builds — but is retained so existing callers do not
+break. Remove it from your `with:` block at leisure.
+
+**Behavior changes without code changes.** A pypi package whose
+`requires-python` spans multiple versions now produces multiple wheels
+where it previously produced one. The `python_version` workflow input
+is inert for pypi builds.
+
+**Verification.** Push a release for a `kind = "pypi"` package whose
+`pyproject.toml` declares `requires-python = ">=3.11"`; the build job
+fans into one wheel row per released version (for example `3.11`,
+`3.12`, `3.13`, `3.14`), and the
+published PyPI release carries a wheel for each.
+
+### pypi bundle_cli binary embeds the release version
+
+**Summary.** The reusable workflow's pypi `[package.bundle_cli]` path
+already rewrote the maturin package's version source before building
+wheels, but the cross-compiled CLI binary comes from the separate crate
+at `bundle_cli.crate_path`. `cargo build` bakes `CARGO_PKG_VERSION`
+from that crate's on-disk `Cargo.toml`, so a wheel could publish as
+`0.3.6` while its bundled CLI reported an older literal such as
+`0.2.7`. The build matrix now rewrites the bundle_cli crate's
+`[package].version` to `matrix.version` immediately before the pypi
+bundle_cli `cargo build`, matching the npm bundled-cli fix.
+
+**Required changes.** None. Consumers who declare `kind = "pypi"`,
+`build = "maturin"`, and `[package.bundle_cli]` get the corrected
+behavior on their next release run against `@v0`; no
+`putitoutthere.toml`, trailer, or consumer-side YAML change is needed.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Same config, different
+artifact: the CLI binary staged into each wheel now reports the
+planned release version from `--version` (and any other
+`CARGO_PKG_VERSION`-derived output) instead of the stale literal in
+the CLI crate manifest.
+
+**Verification.** Release a pypi maturin package that declares
+`[package.bundle_cli]`, install one of the published wheels, and run
+the bundled CLI's `--version`: it reports `<version>`, matching the
+published wheel metadata.
+
+### npm bundled-cli binary embeds the release version
+
+**Summary.** The reusable workflow's npm `build = "bundled-cli"` path
+cross-compiled the bundled CLI from un-rewritten crate source, so the
+binary's `CARGO_PKG_VERSION` (what `<bin> --version` prints) was baked
+from the literal `[package].version` in the crate's `Cargo.toml`
+rather than the planned release version. A `@scope/cli-<triple>@0.3.5`
+platform package could ship a binary that reported `0.2.7`. The build
+matrix now rewrites the crate's `[package].version` to `matrix.version`
+before `cargo build` runs, mirroring the pre-build `write-version`
+step the pypi/maturin path already uses.
+
+**Required changes.** None. The fix lives entirely inside the reusable
+workflow's build matrix. Consumers who declare a `kind = "npm"`
+`build = "bundled-cli"` package with `[package.bundle_cli]` get the
+corrected behavior on their next release run against `@v0`; no
+`putitoutthere.toml`, trailer, or consumer-side YAML change is needed.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Same config, different
+artifact: the cross-compiled binary inside each per-platform package
+now reports the planned release version from `--version` (and any
+other `CARGO_PKG_VERSION`-derived output) instead of the stale literal
+on disk in the crate manifest.
+
+**Verification.** Release a `kind = "npm"` `build = "bundled-cli"`
+package, extract one per-platform package
+(`@scope/cli-<triple>@<version>`), and run the bundled binary's
+`--version`: it reports `<version>`, matching the published package.
+### Bundled-cli staged binary is executable
+
+**Summary.** For `kind = "npm"` packages with a `build = "bundled-cli"`
+entry, the reusable workflow cross-compiles the CLI and stages it into
+a per-triple platform package (`@scope/cli-<triple>`). The staged
+binary was packed with mode `0644` — no executable bit. npm only sets
+the executable bit on `bin` entries; the bundled binary is referenced
+via `package.json#main`, so npm never `chmod`s it, and the bit it had
+on the build runner is stripped crossing the GitHub Actions artifact
+upload/download boundary. At runtime the generated launcher's
+`spawnSync` of the resolved binary failed with `EACCES`. The workflow
+now `chmod +x`es the staged binary for non-Windows targets before the
+platform package is packed/published.
+
+**Required changes.** None. The fix is internal to the reusable
+workflow's npm bundled-cli publish path.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Per-triple platform
+packages published for non-Windows targets now ship the CLI binary
+with mode `0755` instead of `0644`. Consumers who already worked
+around the bug (a `postinstall` `chmod`, or a launcher that `chmod`s
+before `spawnSync`) can drop that workaround; leaving it in place is
+harmless.
+
+**Verification.** Publish a `build = "bundled-cli"` npm family, then
+`npm install` it and run the CLI — `npx <bin> --version` succeeds
+instead of failing with `spawnSync ... EACCES`. Inspecting the
+published platform tarball
+(`tar -tvzf` on the `@scope/cli-<triple>` `.tgz`) shows the binary as
+`-rwxr-xr-x`.
+
+### Pre-merge crate-size check
+
+**Summary.** `putitoutthere check` gained a check that runs
+`cargo package --no-verify` for every `kind = "crates"` package and
+fails when the resulting `.crate` is larger than crates.io's 10 MiB
+(`10485760`-byte) upload limit. Previously an oversized crate — most
+often caused by a tracked symlink dragging a build tree into the
+package — surfaced only mid-release as a `413 Payload Too Large` from
+`cargo publish`, after the verification build. The new check moves
+that failure to PR time, before merge.
+
+**Required changes.** None. The check is additive and runs
+automatically wherever `putitoutthere check` already runs (the
+`check.yml` reusable workflow). For the check to actually measure a
+crate, a Rust toolchain (`cargo`) must be on `PATH` in that job; when
+`cargo` is absent the check degrades to a no-op rather than failing,
+so a check job without Rust set up sees no behavior change.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** A PR that would produce an
+oversized `.crate` now fails `putitoutthere check` with the new
+`PIOT_CRATES_PACKAGE_TOO_LARGE` error code, instead of passing the
+check and failing later inside the release run's publish job.
+
+**Verification.** Add a `kind = "crates"` package and run
+`putitoutthere check` (or open a PR against a repo wired to
+`check.yml`) in an environment with `cargo` on `PATH`: an oversized
+crate reports `PIOT_CRATES_PACKAGE_TOO_LARGE` naming the `.crate`
+size and the 10 MiB limit, while a normally-sized crate reports
+nothing.
+
+### v0 tracks main HEAD
+
+**Summary.** Until this release, the floating `v0` tag advanced only
+when a `release:` trailer fired the dogfood publish pipeline
+(`release-npm.yml`), which then moved `v0` to the latest
+`putitoutthere-v0.x.y` release commit. Commits that landed on main
+without a trailer — test-only changes, docs edits, dependency bumps,
+internal refactors, and one-off bug fixes whose author forgot the
+trailer — left `v0` stale relative to main. The behavior was
+explicitly chosen in issue #199 (`v0` = "latest released commit in
+major line") and is now explicitly reversed: `v0` tracks main HEAD,
+not the latest release.
+
+A new workflow `.github/workflows/advance-v0.yml` fires on every
+push to main, builds the action bundle, folds it into a tag-only
+commit (mirroring `release-npm.yml`'s existing Fold step —
+`dist-action/` is gitignored on main, so `v0` must point at a
+synthesized bundle commit for `uses:
+thekevinscott/putitoutthere@v0` to resolve to a runnable action),
+and force-moves `v0` to that commit. The new workflow shares the
+`release` concurrency group with `release-npm.yml`, so when both
+fire on the same push (a trailer-bearing commit), the registry
+publish runs first and `v0` is then advanced on top.
+
+The permanent per-release tags (`putitoutthere-v0.x.y`) are
+unchanged — they're cut by the dogfood publish pipeline on
+trailer-fire and remain the canonical version history.
+
+**Required changes.** None on the consumer side. The change is in
+how `@v0` resolves over time, not in what the workflow at that ref
+does.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** A commit that lands on
+`main` of `thekevinscott/putitoutthere` is, on the next consumer
+workflow resolve, the workflow code the consumer runs. Previously
+consumers had to wait for a release to be cut to pick up engine
+changes; now they pick them up on the next push to main. Consumers
+who want pinning to a known-released version use a
+`putitoutthere-v0.x.y` tag (or a SHA) instead of `@v0`.
+
+**Verification.** After this change merges and the first push to
+main fires `advance-v0.yml`, the `v0` tag points at a fresh bundle
+commit whose parent is the merge commit on main. Confirm with:
+
+```
+$ git ls-remote --tags https://github.com/thekevinscott/putitoutthere.git v0
+<sha>  refs/tags/v0
+$ git log <sha> -1 --format='%H %s'
+<sha> chore(v0): bundle action
+$ git log <sha>^ -1 --format='%H %s'   # parent is the merge commit on main
+<parent-sha> <merge commit subject>
+```
+
+### Preflight: manifest repository URL must match GITHUB_REPOSITORY; private repos rejected
+
+**Summary.** Two new preflight checks address the
+"surprise-at-publish" failure mode where a manifest's declared
+`repository` URL silently disagrees with the GitHub repository the
+workflow is actually running from. npm's provenance verification
+returns a 422 (`"package.json: repository.url is X, expected to
+match Y from provenance"`) **after** the artifact has been uploaded
+and the registry has done OIDC negotiation — the kind of mid-publish
+surprise this engine's "no release surprises" design commitment
+exists to prevent. The same risk lives on the crates.io / PyPI
+trusted-publisher paths against `Cargo.toml [package].repository`
+and `pyproject.toml [project.urls]`. Both checks now fire at the
+preflight stage before any side effects.
+
+A second new check refuses to publish from a **private** GitHub
+repository entirely. Provenance attestations embed a public
+source-ref pointer that consumers cannot dereference when the repo
+is private; the same source-visibility expectation underpins the
+trusted-publisher story across all three registries. Hard-failing
+at preflight beats silently shipping a verification-broken artifact.
+
+**Required changes.** None for any consumer whose manifest URLs
+already point at the correct `owner/repo` on GitHub and whose
+repository is public. The check is opt-out only by fixing the
+underlying disagreement.
+
+| Failure mode                                                          | Fix                                                                                                                                                                                                                |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `PIOT_REPO_URL_MISMATCH` on a renamed repo, manifests stale.          | Update the manifest URL to match the GitHub repo (recommended), or rename the GitHub repo so the slugs line up. Re-run the release.                                                                                |
+| `PIOT_REPO_URL_MISMATCH` on a manifest that points at a fork or mirror. | Point the manifest URL at the canonical GitHub repo the workflow runs from. Trusted-publisher records on every registry bind to the workflow source, not the fork.                                                 |
+| `PIOT_REPO_PRIVATE` on a repository that is intentionally private.    | This engine cannot publish from a private repository. Either flip the repo to public before releasing or use a different release path. There is no opt-out flag — provenance attestations require public source.   |
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** None — both checks are
+new gates.
+
+**Verification.** From a PR branch with a deliberately-wrong
+`repository.url`, the PR-time `check.yml` job now reports
+`[PIOT_REPO_URL_MISMATCH]` naming both the declared and expected
+`owner/repo` slugs and the manifest path. From a private repo,
+`publish` aborts before any side effect with `[PIOT_REPO_PRIVATE]`.
+Both checks no-op outside a GHA context (when `GITHUB_REPOSITORY`
+is unset), so a local `putitoutthere check` from a developer
+machine does not false-positive.
+
+### Windows default runner pinned to windows-2022
+
+**Summary.** GitHub is migrating `windows-latest` (and `windows-2025`)
+to Visual Studio 2026 between 2026-06-08 and 2026-06-15 — see the
+[GitHub Actions image-migration changelog](https://github.blog/changelog/2026-05-14-github-actions-upcoming-image-migrations/)
+and [actions/runner-images#14016](https://github.com/actions/runner-images/issues/14016).
+Until that date, `windows-latest` is Windows Server 2025 + VS2022; on
+the cutover, `windows-latest` redirects to `windows-2025-vs2026` and
+every consumer release run lands on a fresh toolchain with no
+opportunity to verify it first.
+
+`defaultRunsOn` in `src/plan.ts` previously returned `windows-latest`
+for any Windows-shaped triple, so every consumer release plan that
+included `x86_64-pc-windows-msvc` (the standard windows triple for
+napi, bundled-cli, and maturin builds) inherited that floating label.
+The default is now `windows-2022`: stable, VS2022, no surprise
+migration. Consumers who want to track the floating label or adopt
+VS2026 early opt in via the per-target `{ triple, runner }` override
+that already exists.
+
+**Required changes.** None for consumers who want to stay on a stable
+VS2022 toolchain — the new default does that for them. Consumers who
+want a different image opt in per target:
+
+Before (relied on the floating `windows-latest` default):
+
+```toml
+[[package]]
+name    = "lib-napi"
+kind    = "npm"
+build   = "napi"
+targets = [
+  "x86_64-unknown-linux-gnu",
+  "x86_64-pc-windows-msvc",
+]
+```
+
+After (no change required — `x86_64-pc-windows-msvc` now resolves to
+`windows-2022` by default):
+
+```toml
+[[package]]
+name    = "lib-napi"
+kind    = "npm"
+build   = "napi"
+targets = [
+  "x86_64-unknown-linux-gnu",
+  "x86_64-pc-windows-msvc",
+]
+```
+
+After (opt in to a different image — for example, surface VS2026
+breakage now rather than on the cutover date):
+
+```toml
+targets = [
+  "x86_64-unknown-linux-gnu",
+  { triple = "x86_64-pc-windows-msvc", runner = "windows-2025-vs2026" },
+]
+```
+
+Other valid choices for the `runner` value include `windows-2025`
+(Server 2025 + VS2022 until the cutover, then VS2026), `windows-2022`
+(matches the new default explicitly), and `windows-latest` (preserves
+the previous floating-label behavior).
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Every Windows-shaped
+matrix row's `runs_on` field now resolves to `windows-2022` instead
+of `windows-latest` when no per-target `runner` override is set.
+Per-target overrides win exactly as before — the bare-string-vs-object
+precedence in `defaultRunsOn` is unchanged. The redirect notice
+GitHub injects into every `windows-latest`-targeted run
+(`NOTICE: windows-latest requests are being redirected to
+windows-2025-vs2026 by June 15, 2026`) stops appearing on plans
+generated by the new engine.
+
+**Verification.** Run a release that includes any Windows triple and
+confirm the build job runs on `windows-2022`:
+
+- In the GitHub Actions UI, the per-target build job's "Set up job"
+  step lists `Runner: GitHub Actions <n>` followed by an OS-image
+  block whose `Image: windows-2022` line names the pinned image. The
+  banner `windows-latest requests are being redirected to
+  windows-2025-vs2026 by June 15, 2026` no longer appears in the
+  job log.
+- The published artifact's `runs_on` value, surfaced in the plan
+  step's job summary, is `windows-2022`.
+
+To opt in to a different image, set
+`{ triple = "x86_64-pc-windows-msvc", runner = "<choice>" }` on the
+relevant target and re-release; the build job moves to the named
+image on the next run.
+
+### Crates first-publish TP rejection detected
+
+**Summary.** crates.io's Trusted Publishing feature binds to an
+already-published crate name. The very first publish of a brand-new
+crate cannot use the TP path — the OIDC mint succeeds, the exchanged
+token reaches cargo, but the registry rejects the publish with a 404
+("crate `<name>` does not exist or you do not have permission to
+publish to it"). The engine previously surfaced this as a generic
+`cargo publish failed` block, sending consumers down a credentials
+rabbit-hole when the real fix is one bootstrap publish via the
+classic-token fallback shipped in #283.
+
+The crates handler now detects this exact response shape and throws
+with the new stable error code
+`PIOT_CRATES_FIRST_PUBLISH_TP_REJECTED`, prefixed onto a message
+that names the crate, explains the TP-binds-to-published-crate
+constraint, and points at `CARGO_REGISTRY_TOKEN` as the bootstrap
+path. Cargo's full stderr is preserved at the bottom of the error
+for debuggability. Companion work landed a registry-auth response
+fixtures catalogue at
+[`notes/upstream-behaviors.md`](./notes/upstream-behaviors.md) that
+indexes this and three other response shapes the engine handles or
+architecturally avoids — see #296.
+
+**Required changes.** None. Consumers who never hit the
+first-publish path see no change. Consumers whose first release
+fails on a brand-new crate now see a clearer error pointing at the
+fix; the fix itself (set `CARGO_REGISTRY_TOKEN` as a workflow
+secret for one publish, then remove it) has been available since
+#283 and is unchanged.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** A `cargo publish`
+failure whose stderr matches the first-publish-TP-rejection shape
+now throws with `PIOT_CRATES_FIRST_PUBLISH_TP_REJECTED` instead of
+the generic `cargo publish failed` shape. The full cargo stderr
+remains in the error message. The detector is suppressed under the
+`PIOT_CRATES_REGISTRY_PRIMARY` e2e seam (alt-registry doesn't model
+TP, so a 404 there is a different bug).
+
+**Verification.** On a brand-new crate name where Trusted
+Publishing is the only auth configured, run the release. The
+release run fails with a message starting
+`[PIOT_CRATES_FIRST_PUBLISH_TP_REJECTED] cargo publish: crates.io
+rejected publishing "<name>" because the crate has never been
+published.` followed by the bootstrap hint. Set
+`CARGO_REGISTRY_TOKEN` in the workflow's `secrets:` block (per
+#283), re-run, and the publish should succeed. Subsequent releases
+can drop the secret and rely on Trusted Publishing.
+
+### Bundled-CLI launcher generated by the workflow
+
+**Summary.** Bundled-CLI npm consumers used to author `bin/<bin>.js` —
+a Node launcher that detects the host platform, maps it to a triple,
+resolves the corresponding `<name>-<triple>` (or templated) platform
+package, and execs the binary. The launcher's only per-consumer
+inputs are the package name and the configured `targets` list. Both
+are in the engine's hands at plan time. Every consumer's launcher
+was byte-identical modulo those two values.
+
+`_matrix.yml`'s build job now invokes a new internal `putitoutthere
+write-launcher` CLI subcommand on the main row of each `kind = "npm"
+&& build = "bundled-cli"` package (before `npm run build --if-present`
+runs). The subcommand writes `bin/<bundle_cli.bin>.js` and adds the
+matching `package.json#bin` entry in place. Both writes are guarded
+by an "only if absent" check — existing consumer-authored launchers
+and existing `bin` fields are preserved, so the override path is the
+same file you'd already have committed.
+
+The generated launcher's shape mirrors the README example bundled-cli
+consumers wrote by hand pre-#299: hashbang, a Node
+`${platform}-${arch}` → triple table, `require.resolve` against the
+platform package, `spawnSync` with `stdio: 'inherit'`. The platform
+package's name template (`{name}-{triple}` by default, or whatever the
+consumer set under `build = [{ mode = "bundled-cli", name = "..." }]`
+in the multi-mode array form) has every placeholder except `{triple}`
+resolved at generation time; `{triple}` becomes a backtick template
+substitution at install time. The launcher imports nothing from
+putitoutthere at runtime — it's a self-contained Node script with no
+published-package dependencies.
+
+Together with #298 (which absorbed the cross-compile build script),
+bundled-cli npm's consumer surface is now: declare the package in
+`putitoutthere.toml`, register Trusted Publishers, push.
+
+**Required changes.** None for new consumers — declaring the package
+in `putitoutthere.toml` is sufficient.
+
+For consumers who already shipped a hand-authored launcher and want
+to migrate to the generated one, delete `bin/<bin>.js` from the source
+tree. The build job will regenerate it on the next release run.
+Leaving the file in place is fully supported; the workflow only
+writes when the file is absent.
+
+```diff
+  // packages/my-cli/package.json
+  {
+    "name": "my-cli",
+-   "bin": { "my-cli": "bin/my-cli.js" }
+  }
+```
+
+Removing the `bin` field is optional too: when the workflow sees an
+existing `bin` field it leaves it alone. The diff above is only
+necessary if the consumer wants the workflow to author the field
+shape from scratch (`{ "<bin>": "bin/<bin>.js" }`).
+
+**Deprecations removed.** None — the legacy hand-authored launcher
+path is still supported and the workflow respects the override.
+
+**Behavior changes without code changes.**
+
+- The published main package's `package.json#bin` now contains
+  `{ "<bundle_cli.bin>": "bin/<bundle_cli.bin>.js" }` for consumers
+  who previously had no `bin` field. Consumers with a pre-existing
+  `bin` field see no change.
+- The published main package's tarball now contains
+  `bin/<bundle_cli.bin>.js` for consumers who previously did not
+  commit the file. Consumers who committed the file see their version
+  shipped unchanged.
+
+**Verification.** After a release run, inspect the published main
+package's tarball:
+
+```sh
+npm pack <main-pkg-name>@<version>
+tar -xvf <main-pkg-name>-<version>.tgz package/bin/<bundle_cli.bin>.js -O \
+  | head -20
+```
+
+The first line is `#!/usr/bin/env node`; the file declares a `triples`
+object whose keys match the Node `${platform}-${arch}` strings the
+package's `targets` resolve to, and whose values are the configured
+triples. `package/package.json`'s `bin` field is
+`{ "<bundle_cli.bin>": "bin/<bundle_cli.bin>.js" }`.
+
+### `bundle_cli` wheel guard respects `python-source`
+
+**Summary.** Maturin's standard mixed-project layout
+(`maturin new --mixed` generates `[tool.maturin].python-source = "python"`)
+declares a package source root that maturin strips from on-disk paths
+when rewriting them into the wheel's distribution layout. A binary
+staged on disk at `<pkg.path>/<stage_to>/<bin>` — e.g.
+`packages/python/python/dirsql/_binary/dirsql` — ends up in the wheel
+at `dirsql/_binary/dirsql`, with `python/` stripped. The reusable
+workflow's `bundle_cli` wheel-content guard previously asserted a
+literal `<stage_to>/<bin>` suffix inside the produced wheel; the regex
+never matched the stripped path, so the guard fired red on every
+per-target build row even when the binary was correctly bundled.
+
+The guard now reads `[tool.maturin].python-source` (and the legacy
+`python_source` spelling — both forms are accepted by maturin across
+versions) from `<matrix.path>/pyproject.toml` and subtracts that
+prefix from `stage_to` before constructing the suffix regex. Consumers
+with an implicit-root layout (no `python-source` key, or an empty
+value) keep the previous behavior byte-for-byte; consumers with the
+explicit-root layout start passing the guard. Tracked at #338.
+
+**Required changes.** None.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.**
+
+- For a consumer with `[tool.maturin].python-source = "python"` and
+  `[package.bundle_cli].stage_to = "python/dirsql/_binary"`, the
+  reusable workflow's wheel-content guard now resolves the in-wheel
+  suffix to `dirsql/_binary/<bin>` (matching what maturin actually
+  produces) instead of asserting the unstripped `python/dirsql/_binary/<bin>`.
+- A `python-source` value that isn't actually a prefix of `stage_to`
+  is left alone — the guard reverts to asserting the unstripped
+  `stage_to` so the consumer's misconfiguration surfaces with the same
+  diagnostic it does today.
+- An unset or empty `python-source` value resolves to the empty
+  string and `stage_suffix` is unchanged. No behavior change for
+  consumers who don't use the explicit-root layout.
+
+**Verification.** With a maturin package whose `pyproject.toml`
+declares `[tool.maturin].python-source = "python"` and whose
+`[package.bundle_cli]` sets `stage_to = "python/<pkg>/_binary"`,
+a release run should produce wheels whose `unzip -l` listing contains
+`<pkg>/_binary/<bin>` and the wheel-content guard step should log
+`ok bundle_cli: <pkg>/_binary/<bin> present in <wheel>`.
+
+### `bundle_cli` cargo workspace
+
+**Summary.** Two collided bugs made `[package.bundle_cli]`
+unsatisfiable for the standard cargo-workspace layout: a single
+workspace root `Cargo.toml` with `[workspace] members = [...]` and the
+`[[bin]]` declared in a member crate (the shape `cargo new --workspace`
+produces, and what the polyglot Rust/Python recipe in the README
+implies). With `crate_path = "."` (the default), `putitoutthere check`
+parsed the workspace root `Cargo.toml` literally, saw no `[[bin]]`, and
+emitted `bundle_cli.bin "X" is not declared as a [[bin]]`. With
+`crate_path = "packages/rust"`, the check passed but the reusable
+workflow's bundle_cli stage step couldn't find the produced binary —
+cargo writes to the workspace-rooted target dir by default
+(`<repo-root>/target/...`), not to the working-directory-rooted one
+(`packages/rust/target/...`) the stage step assumed. There was no
+`crate_path` value that satisfied both halves.
+
+The check now walks `[workspace].members` and aggregates each member's
+declared bins (honoring the implicit-binary rule, including
+`[package].name = { workspace = true }` inheritance from
+`[workspace.package].name`). The reusable workflow's cargo build step
+pins `--target-dir target` so the produced binary is deterministically
+at `${{ matrix.bundle_cli.crate_path }}/target/<triple>/release/<bin>`
+regardless of whether the crate participates in a workspace. Tracked at
+#337.
+
+**Required changes.** None.
+
+Consumers whose `[package.bundle_cli]` block already worked (single-
+crate layouts, or workspaces where `crate_path` pointed directly at the
+member crate and the consumer's project structure happened to make the
+workspace target dir line up with the member target dir) keep building
+byte-identically. Consumers whose workspace layout previously failed
+the check or stage step start working without touching their config.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.**
+
+- `putitoutthere check` accepts the cargo-workspace shape:
+  ```toml
+  # /Cargo.toml
+  [workspace]
+  members = ["packages/rust"]
+
+  # /packages/rust/Cargo.toml
+  [package]
+  name = "my-cli"
+  description = "..."
+  license = "MIT"
+
+  [[bin]]
+  name = "my-cli"
+  path = "src/main.rs"
+
+  # /putitoutthere.toml
+  [package.bundle_cli]
+  bin      = "my-cli"
+  stage_to = "python/dirsql/_binary"
+  # crate_path defaults to "."
+  ```
+  previously reported `bundle_cli.bin "my-cli" is not declared as a [[bin]]`,
+  now reports zero findings.
+- The reusable workflow's bundle_cli build step now passes
+  `--target-dir target` to `cargo build`. The produced binary is at
+  `${{ matrix.bundle_cli.crate_path }}/target/<triple>/release/<bin>`
+  regardless of workspace membership, and the stage step's `src=` path
+  resolves correctly by construction.
+- Members declared as glob patterns (`members = ["packages/*"]`) are
+  expanded against the filesystem by the check — see
+  [`bundle_cli` glob workspace members](#bundle_cli-glob-workspace-members).
+
+**Verification.** With the workspace layout above, the consumer should
+see:
+
+- `putitoutthere check` reports zero findings.
+- A maturin release run produces a wheel whose `unzip -l` includes the
+  staged binary (the existing wheel-content guard asserts this).
+
+### `bundle_cli` glob workspace members
+
+**Summary.** The `bundle_cli` cargo-workspace fix above taught
+`putitoutthere check` (and the pre-publish preflight) to walk
+`[workspace].members` and aggregate each member crate's declared
+`[[bin]]` entries, so `crate_path = "."` resolves a `[[bin]]` that
+lives in a member crate. That walk only handled *literal* member
+entries. cargo `members` entries are globs, and `members =
+["packages/*"]` — a Rust core crate under `packages/rust` wrapped by
+sibling Python / npm packages — is the standard polyglot-repo shape. A
+glob entry never resolved to a literal `<member>/Cargo.toml`, so the
+member crate's `[[bin]]` went unseen and `crate_path = "."` was
+rejected with `bundle_cli.bin "X" is not declared as a [[bin]]`.
+
+The check now expands `[workspace].members` glob entries against the
+filesystem the way cargo resolves them; a member crate behind a glob is
+found like any literal member.
+
+**Required changes.** None.
+
+Consumers whose workspace declares `members` with literal paths are
+unaffected. Consumers who declared `members` with a glob and worked
+around the rejected check — by also listing the member crate as a
+literal entry, or by pointing `crate_path` straight at the member
+crate — can drop the workaround and let `crate_path` default to `"."`.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.**
+
+- `putitoutthere check` accepts a glob-member workspace:
+  ```toml
+  # /Cargo.toml
+  [workspace]
+  members = ["packages/*"]
+
+  # /packages/rust/Cargo.toml
+  [package]
+  name = "rust-core"
+
+  [[bin]]
+  name = "my-cli"
+  path = "src/main.rs"
+
+  # /putitoutthere.toml
+  [package.bundle_cli]
+  bin      = "my-cli"
+  stage_to = "python/dirsql/_binary"
+  # crate_path defaults to "."
+  ```
+  previously reported `bundle_cli.bin "my-cli" is not declared as a [[bin]]`,
+  now reports zero findings.
+
+**Verification.** With the glob-member workspace above, `putitoutthere
+check` reports zero findings.
+
 ### Crates metadata check resolves `[workspace.package]` inheritance
 
 **Summary.** Cargo's recommended pattern for shared crate metadata in a
@@ -396,6 +1578,56 @@ the same path the launcher resolves it from.
 
 ---
 
+### Preflight pyproject + cargo shape
+
+**Summary.** Preflight gains two more checks — `requirePyprojectShape`
+and `requireCargoShape` — that mirror the #280 / #290 pattern for
+`pyproject.toml` (pypi packages) and `Cargo.toml` (crates packages,
+plus `bundle_cli` on pypi packages). The maturin / setuptools /
+hatchling / cargo CLIs surface mismatched-shape errors 10-20 minutes
+into a release run, deep into the verification build, with messages
+that don't name the precondition that failed. The new checks fire at
+publish time alongside the existing `require*` family and at PR time
+via `check.yml`. Findings aggregate across every failing package so
+consumers fix them all in one round-trip, exactly the shape the prior
+checks established. #301.
+
+**Required changes.** None for well-formed manifests. Repos that
+declared one of the documented mismatches below previously got a
+mid-release red; they now get a fast preflight red instead.
+
+The new error codes:
+
+| Code | Fires when |
+|------|------------|
+| `PIOT_PYPI_NAME_MISMATCH` | `pyproject.toml`'s `[project].name` differs from `[[package]].name` (or the `pypi` override). |
+| `PIOT_PYPI_BUILD_BACKEND_MISMATCH` | `[build-system].build-backend` is set and does not start with the prefix the configured `build` mode expects (`maturin` → `maturin`, `setuptools` → `setuptools`, `hatch` → `hatchling`/`hatch`). |
+| `PIOT_PYPI_DYNAMIC_VERSION_NO_BACKEND` | `[project].dynamic` includes `"version"` but neither `[tool.hatch.version]` nor `[tool.setuptools_scm]` is present. |
+| `PIOT_PYPI_MATURIN_INCLUDE_MISSING` | `bundle_cli` is set but `[tool.maturin].include` does not cover `bundle_cli.stage_to`. |
+| `PIOT_CRATES_NAME_MISMATCH` | `Cargo.toml`'s `[package].name` differs from `[[package]].name` (or the `crate` override). |
+| `PIOT_CRATES_MISSING_BIN` | `bundle_cli.bin` is set but the target `Cargo.toml` has no `[[bin]]` table with that name (and the implicit-bin name derived from `[package].name` does not match either). |
+| `PIOT_CRATES_FEATURE_NOT_DECLARED` | `features` (on `kind = "crates"` packages) or `bundle_cli.features` references a feature not declared in `[features]`. |
+| `PIOT_CRATES_WORKSPACE_VERSION_MISMATCH` | `[package].version.workspace = true` but no ancestor `Cargo.toml` declares `[workspace.package].version`. |
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Repos with one of the
+shapes above used to get a confusing mid-release error from
+maturin / setuptools / hatchling / cargo (sometimes after a
+verification build of every transitive dep); they now get a
+fingerprintable `PIOT_*` error at preflight time, before any side
+effects. PR-time `check.yml` runs surface the same findings on
+every pull request, so the typical case is fix-before-merge rather
+than fix-after-release-red. The `[build-system].build-backend`
+check is deliberately narrow: a missing `[build-system]` table is
+allowed (pip falls back to setuptools), and the prefix match
+tolerates backend-version drift across maturin / setuptools /
+hatchling.
+
+**Verification.** Misconfigure one field, run `pnpm putitoutthere
+check` (or open a PR with `check.yml` wired), see the relevant
+`PIOT_*` code surface in seconds instead of mid-release.
+
 ### New `check.yml` reusable workflow for PR-time config sanity
 
 **Summary.** `putitoutthere` now ships a third reusable workflow,
@@ -805,6 +2037,48 @@ step (one in the build matrix, one in the publish-job rebuild)
 when the strict install fails; healthy installs see no
 warning.
 
+### Platform-publish `.npmrc` lookup
+
+**Summary.** The reusable workflow's per-triple platform-package
+publishes (`build = "bundled-cli"` / `build = "napi"`) ran `npm
+publish` from a temporary staging directory rather than from the
+consumer's package path. npm reads `.npmrc` from cwd upward; the
+consumer's `.npmrc` lives at `pkg.path`, never on the path to a
+tempdir, so platform publishes never saw the auth the main package
+relied on. OIDC trusted publishing masked the gap (auth flows via
+the `ACTIONS_ID_TOKEN_REQUEST_TOKEN` environment variable, not
+`.npmrc`), but the `NPM_TOKEN` bootstrap path (#310) — required
+for the very first publish of a brand-new npm package — and the
+internal Verdaccio e2e seam (#304) both broke because both rely on
+`.npmrc`-supplied auth.
+
+The engine now invokes `npm publish <stagingDir>` with `cwd:
+pkg.path`, matching how the main-package publish already runs.
+npm reads the consumer's `.npmrc` (including any `_authToken`,
+`always-auth`, or scoped-registry entries) and applies it to the
+PUT for each per-triple platform package.
+
+**Required changes.** None. The fix is internal to
+`src/handlers/npm-platform.ts`; consumer `release.yml` flows are
+unchanged.
+
+**Deprecations removed.** None.
+
+**Behavior changes without code changes.** Consumers who rely on
+`NPM_TOKEN` (rather than OIDC) for the first publish of a
+bundled-cli / napi family — i.e. a brand-new npm package whose
+per-triple sub-packages also don't exist yet — now succeed without
+the workaround of publishing a `0.0.0-bootstrap` stub by hand.
+OIDC consumers see no observable difference: the same env-derived
+auth keeps flowing because `npm publish` reads
+`NODE_AUTH_TOKEN`/`ACTIONS_ID_TOKEN_REQUEST_TOKEN` from the
+environment regardless of which directory cwd points at.
+
+**Verification.** A consumer publishing a brand-new bundled-cli /
+napi family via `NPM_TOKEN` completes per-triple sub-package
+publishes alongside the main package on the first release run,
+with no `npm publish (platform) failed` errors in the log.
+
 ### `[package.bundle_cli]` now actually stages the binary
 
 **Summary.** Wheels published from a maturin pypi package that