# REF-068: npm Dist-Tags and Lockfile Integrity

## Citation

npm. (2026). *Package metadata response documentation*. npm registry repository.
<https://github.com/npm/registry/blob/master/docs/responses/package-metadata.md>

npm. (2026). *package-lock.json*. npm CLI documentation.
<https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json/>

npm. (2026). *Adding dist-tags to packages*. npm documentation.
<https://docs.npmjs.com/adding-dist-tags-to-packages/>

## Document Profile

| Attribute | Value |
| ----------- | ------- |
| Year | 2026 |
| Type | Package registry and CLI documentation |
| Status | Active operational standard for JavaScript package distribution |
| GRADE / Quality | A- - official implementation documentation for a dominant package ecosystem |
| AIWG Relevance | High - Provides the nearest operator model for channels, exact resolution, and lockfiles |

## Executive Summary

npm separates human-facing version selection from reproducible installation.
Package metadata exposes `dist-tags` such as `latest` as labels that map to
published versions, while lockfiles record the exact dependency tree and
integrity material needed for repeatable installs.

For AIWG, this is the clearest precedent for treating `stable`, `latest`,
`canary`, and `main` as mutable selectors that must resolve to exact immutable
resource releases. It also supports the current `.aiwg/resources.lock.json`
shape: persist the selector for auditability, but pin the resolved version,
manifest URL, manifest digest, and content digests for reproducibility.

## AIWG Implementation Mapping

| npm Pattern | AIWG Resource Pattern |
| ------------- | ----------------------- |
| `dist-tags` map labels to versions | Channel manifests map channel names to exact AIWG resource versions |
| `latest` is conventional, not immutable | `stable`/`latest` are pointers, not cache identities |
| `package-lock.json` records exact tree | `.aiwg/resources.lock.json` records exact resource release state |
| Integrity metadata protects fetched bytes | Manifest and descriptor SHA-256 values protect resource bytes |

## Design Implications

- Do not cache a channel name as if it were a release. Cache the exact resolved
  version plus manifest digest.
- Lockfile writes should be explicit. A read-only discover/show command should
  not silently change project reproducibility state.
- Offline mode should rely on lockfile/cache identity and fail closed when the
  required bytes are missing or drift from their recorded digest.

## Cross-References

- REF-067: SemVer supplies version ordering expectations used by npm-like
  registries.
- REF-071: SRI supplies the browser analogue for verifying fetched bytes.
- REF-072: TUF supplies rollback and metadata freshness protections beyond
  simple integrity fields.
- `docs/install/web-backed-resources.md`: AIWG resource lockfile contract.
