Skip to content

ADR-015: Fix unsatisfiable npm version ranges - #2

Merged
nicholas-ruest merged 1 commit into
mainfrom
adr-015/fix-npm-version-ranges
Jul 27, 2026
Merged

ADR-015: Fix unsatisfiable npm version ranges#2
nicholas-ruest merged 1 commit into
mainfrom
adr-015/fix-npm-version-ranges

Conversation

@nicholas-ruest

Copy link
Copy Markdown
Member

Implements step 14 of ADR-015: Platform Package Naming Authority and Dependency Name Resolution (Kind C — unresolvable version).

Unrelated to open PR #1 (ADR-0001); separate branch, no overlap.

The bug

Two optionalDependencies in package.json declared caret ranges that no published version satisfies:

Package Declared Published Fixed to
@llm-dev-ops/llm-cost-ops-sdk ^0.1.0 1.0.0, 1.0.1 ^1.0.1
@llm-dev-ops/llm-config-core ^0.1.0 0.5.0 ^0.5.0

Both fail for the same semver reason, though it's worth being precise about the second one since it looks satisfiable at a glance:

  • A caret range never crosses a major boundary, so ^0.1.0 cannot reach 1.0.1.
  • For 0.x versions the caret is narrower still — it pins the minor. ^0.1.0 desugars to >=0.1.0 <0.2.0, so 0.5.0 does not satisfy it either.

Why this went unnoticed

These are optionalDependencies. npm silently drops optional deps it cannot resolve and still exits 0 — so the failure never surfaced as an install error. The packages were simply absent from the tree, and any require() of them would have failed at runtime instead.

Verification (real output)

Before — both ranges 404 against the live registry:

$ npm view "@llm-dev-ops/llm-cost-ops-sdk@^0.1.0" version
npm error code E404
npm error 404 No match found for version ^0.1.0

$ npm view "@llm-dev-ops/llm-config-core@^0.1.0" version
npm error code E404
npm error 404 No match found for version ^0.1.0

Before — resolution reports success, but the two packages are missing from the tree while their siblings resolve fine:

$ npm install --package-lock-only --no-audit --no-fund
up to date in 45s

@llm-dev-ops/llm-cost-ops-sdk -> 0 entries     <-- silently dropped
@llm-dev-ops/llm-config-core  -> 0 entries     <-- silently dropped
@llm-dev-ops/sentinel-cli     -> 1 entries
@llm-dev-ops/observatory-sdk  -> 1 entries

After — both ranges resolve:

$ npm view "@llm-dev-ops/llm-cost-ops-sdk@^1.0.1" version
1.0.1
$ npm view "@llm-dev-ops/llm-config-core@^0.5.0" version
0.5.0

After — both now present in the resolved tree:

@llm-dev-ops/llm-cost-ops-sdk -> RESOLVED v1.0.1  (https://registry.npmjs.org/@llm-dev-ops/llm-cost-ops-sdk/-/llm-cost-ops-sdk-1.0.1.tgz)
@llm-dev-ops/llm-config-core  -> RESOLVED v0.5.0  (https://registry.npmjs.org/@llm-dev-ops/llm-config-core/-/llm-config-core-0.5.0.tgz)

After — full npm install, exit 0, packages physically on disk:

$ npm install --no-audit --no-fund --ignore-scripts
added 12 packages, removed 4 packages, and changed 32 packages in 3m
EXIT=0

$ node -p "require('./node_modules/@llm-dev-ops/llm-cost-ops-sdk/package.json').version"
1.0.1
$ node -p "require('./node_modules/@llm-dev-ops/llm-config-core/package.json').version"
0.5.0

Note: package-lock.json is gitignored in this repo (.gitignore:51), so no lockfile change is included.

Range choice

No source file imports either package — grep across src/ and tests/ found references only in package.json and the Phase 2B docs table. So no code constraint dictates the range; ^1.0.1 and ^0.5.0 were chosen to track the current published version and stay within its compatible range. Also updated the matching rows in docs/PHASE_2B_INFRA_INTEGRATION_REPORT.md.

Not addressed here

Scoped to the two ranges ADR-015 names. The other four optionalDependencies (@llm-devops/latency-lens, @llm-dev-ops/sentinel-cli, llm-shield-core, @llm-dev-ops/observatory-sdk) were left alone. sentinel-cli and observatory-sdk were observed resolving correctly; the other two were not audited in this PR. Worth a follow-up sweep given the same silent-skip behaviour would hide an identical bug.

Two optionalDependencies declared caret ranges that no published version
satisfies:

  @llm-dev-ops/llm-cost-ops-sdk  ^0.1.0 -> ^1.0.1  (published: 1.0.0, 1.0.1)
  @llm-dev-ops/llm-config-core   ^0.1.0 -> ^0.5.0  (published: 0.5.0)

Both fail for the same semver reason. A caret range does not cross a major
boundary, so ^0.1.0 cannot reach 1.0.1. For 0.x the range is narrower still:
^0.1.0 desugars to >=0.1.0 <0.2.0, which excludes 0.5.0.

Because these sit in optionalDependencies, npm skipped them silently and
still reported success, so the failure never surfaced as an install error.
@nicholas-ruest
nicholas-ruest merged commit 114865b into main Jul 27, 2026
2 of 9 checks passed
@nicholas-ruest
nicholas-ruest deleted the adr-015/fix-npm-version-ranges branch July 27, 2026 20:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant