Pinned CLI installs are not reproducible: ship npm-shrinkwrap.json and drop the unbounded runtime @types/node dependency

[unbraind]

Problem

npm install -g @unbrained/pm-cli@<exact version> is not reproducible: the published package has no npm-shrinkwrap.json, so every install re-resolves the transitive tree from caret ranges at install time. Pinning the CLI version pins nothing below it.

On 2026-10-06 this broke every CI job that installs a pinned CLI, with no change on our side:

npm install -g @unbrained/pm-cli@2026.10.5
npm error code ETARGET
npm error notarget No matching version found for @opentelemetry/resources@2.12.0.

A few minutes later the same command failed with E404 GET .../@opentelemetry/sdk-trace/-/sdk-trace-2.12.0.tgz. The OpenTelemetry 2.12.0 release was propagating: the packuments already listed 2.12.0 (published 13:40:53Z; our failing install ran at 13:40:43Z) before the tarballs were served. The packages come in transitively through @sentry/node (pinned at 10.75.1, but its own OpenTelemetry deps use ^ ranges). Every downstream repo that pins @unbrained/pm-cli@X as a test oracle or tool failed at once: Linux, macOS and Windows jobs, required checks included.

Related: dependencies includes "@types/node": ">=22". That is an unbounded range on a type-only package, so a global install pulls whatever @types/node major is newest. Type definitions are not needed at runtime, and an open-ended >= is the least reproducible range there is.

Proposal

1. Publish npm-shrinkwrap.json with the CLI package (npm honours it for both npm i -g and npx), generated from the release lockfile that CI actually tested. A pinned CLI version then installs exactly the tree that passed the release gates. Bun's bunx/bun add -g ignore shrinkwrap, so also document --frozen-lockfile-equivalent guidance, or accept that Bun floats.
2. Move @types/node to devDependencies. If consumers of the SDK types need it, use peerDependencies + peerDependenciesMeta.optional, with a bounded range (^22 || ^24 || ^26).
3. Optional: a release gate that installs the packed tarball with --prefer-offline=false into an empty prefix, and fails if the resolved tree differs from the tested lockfile.

Acceptance

• npm view @unbrained/pm-cli@<next> _hasShrinkwrap is true.
• Installing the same CLI version on two different days resolves byte-identical node_modules (same integrity hashes).
• @types/node is no longer a runtime dependency.

[unbraind]

Canonical release/CI lineage: pm-u9d0, with recurring installed-artifact observation under pm-7zs0.

The current all-status keyword search finds no shrinkwrap-specific item. This new report remains open for the next reviewed delivery; the reported registry propagation failure has not been independently reproduced here. A release-lock design must prove npm/global/npx resolution and Bun behavior against the tested artifact, and check SDK declaration consumers before changing the Node type dependency. Existing successful installed-consumer results do not establish reproducibility across publication times. No duplicate item or dependency-policy exception is introduced.

[unbraind]

Canonical implementation owner: pm-gh1417.

The implementation, local verification and immutable closure evidence are included in PR #1421.

[unbraind]

Implementation decision for PR #1421: the original _hasShrinkwrap=true criterion describes a proposed npm-specific mechanism. The verified implementation instead publishes the tested physical production closure as bundled dependencies, with a deterministic integrity ledger, exact installed-version checks, and separate fail-closed runtime budgets. Temporary acceptance verified all 40 runtime package identities through npm global installation with an empty offline cache, Bun installation, npx and bunx, plus an installed public SDK TypeScript consumer. @types/node is a bounded optional peer and development dependency.

The tarball contains no npm-shrinkwrap.json and this PR therefore does not satisfy the literal _hasShrinkwrap metadata assertion. Bundling addresses the underlying registry re-resolution failure for npm and Bun together; the original report and proposed acceptance are retained for provenance. Cross-day installation of the next published version remains a publication observation rather than a completed test on an unpublished artifact. Canonical evidence: pm-gh1417.