Pantry package manager

This reference is reproduced from Pantry v0.10.36 at immutable commit a6bdc42071cc659896d1b9ff9d7ab6862c72954d. The copied contract and its executable evidence are checksummed in evidence/pantry/evidence.lock.json. Stacks relies on this boundary; it does not redefine Pantry behavior.

The text below is the upstream implementation contract. Normative words apply to Pantry at the pinned revision, not to every historical Pantry version.

This document describes the package-manager behavior implemented by the native Zig CLI in packages/zig. It is a contract and operations reference, not a list of intended features. bun run docs:contracts:check links every critical claim below to its command registration or implementation source and fails CI when the documentation drifts.

Scope and source of truth

Pantry manages three related dependency classes:

The generated system catalog is local to the CLI, so normal search and package classification do not require an online third-party catalog. Live Pantry-registry search supplements the generated catalog for newly published packages. npm is a separate compatibility and JavaScript dependency source; it is not Pantry's system-package registry.

Manifest discovery and precedence

Pantry recognizes project manifests including pantry.json, package.json, and the YAML dependency files documented in the quick start. A workspace root owns a single pantry.lock; workspace package constraints are recorded separately from their resolved package entries. Explicit CLI package arguments narrow or extend the manifest operation depending on the command.

Configuration precedence is:

1. explicit command options;
2. project configuration (pantry.toml and supported dependency manifests);
3. environment settings;
4. compiled defaults.

--no-save prevents both manifest and lockfile writes. --force intentionally bypasses the normal lockfile/cache fast paths and resolves again. These options are not equivalent: forcing a refresh does not imply that state must be saved.

Install and resolution commands

Install option semantics

Resolution and install pipeline

The normal project operation follows this order:

1. Discover the effective project/workspace root and dependency manifest.
2. Read pantry.lock and determine whether recorded constraints still match.
3. Use the lockfile fast path when every package is resolvable and destination content exists; otherwise resolve missing or changed packages.
4. Classify each spec as a Pantry system package, npm package, workspace package, local link, Git source, or another supported source.
5. Resolve exact versions and tarball URLs, retaining integrity metadata when the upstream registry supplies it.
6. Download in parallel unless offline or satisfied by cache.
7. Verify any supplied integrity claim before extraction.
8. Extract into managed content, create executable shims/links, and run permitted lifecycle hooks.
9. Update the lockfile only after successful results and only when writes are allowed.

Partial failures return a non-zero command result. Quiet mode may remove progress noise but cannot convert a failure into success or hide its final reason.

Lockfile contract

pantry.lock is the reproducibility boundary. It records exact package versions, resolved locations, integrity when available, dependency relationships, and workspace constraint state. It supports lockfile-first restore, which avoids redundant registry resolution, and frozen validation, which compares the computed result to committed state and rejects a missing or changed lockfile.

The lockfile does not create integrity evidence when an upstream package supplies none. Such an entry is reproducible by version and URL but has weaker content authentication and must not be described as cryptographically verified.

Integrity, cache, and extraction

For npm-style tarballs, Pantry verifies a supplied raw SHA-256 digest or SRI sha256, sha512, or legacy sha1 value. A mismatch, malformed base64 value, missing algorithm separator, or unsupported algorithm fails closed. When no integrity claim exists, the installer can still validate archive structure and uses the content cache's SHA-256 bookkeeping, but that is not equivalent to an upstream-authenticated digest.

Downloaded content is cached by package, version, source, and checksum. A poisoned cache entry that fails verification or extraction is evicted and may be fetched again when networking is allowed. --offline never silently crosses the network; if verified content is unavailable locally, the install fails.

Native archives are validated for expected archive structure. When a valid sidecar checksum is available, it is checked before extraction. Absence of a sidecar is explicitly weaker than a verified sidecar and is not a signature.

Lifecycle scripts and trust

Lifecycle scripts execute dependency code and are therefore a separate trust decision from checksum validation. Pantry supports pantry trust, pantry untrusted, and pantry default-trusted for managing that decision. --ignore-scripts is the deterministic opt-out for CI or security-sensitive installs. An integrity match proves bytes match the declared digest; it does not prove that running those bytes is safe.

Workspaces and local development

Workspace installs use the workspace root for pantry.lock, resolve workspace: ranges before publication, deduplicate shared external packages where compatible, and retain per-workspace declared constraints. --filter limits the selected workspace set. Local links are recorded in Pantry's link registry and avoid a publish round trip; they are mutable development inputs and do not carry normal immutable-registry guarantees.

Publication channels

Pantry-registry publication and npm publication are intentionally different surfaces. The command and selected registry determine the protocol; Pantry does not transparently republish every npm dependency.

Environment and installation locations

Project installs live in Pantry-managed project environments. Global installs select the system prefix when writable, while --user selects the user-owned global data directory. Custom paths are explicit and should be treated as an operator choice because ownership, PATH behavior, and cleanup boundaries change.

Shell integration performs environment lookup on directory changes. The environment identity incorporates project location and dependency state so two projects, or two dependency revisions of one project, do not accidentally share an incompatible active toolchain. Leaving the project restores the previous environment instead of copying packages into the global shell.

Failure modes operators should preserve

• Unknown package, impossible version, invalid manifest, or malformed lockfile: fail with the package/config cause.
• Frozen lockfile missing or divergent: fail without modifying it.
• Offline cache miss: fail without a network fallback.
• Integrity mismatch or unsupported integrity algorithm: fail before extraction.
• Untrusted lifecycle script: require trust or an explicit script policy.
• Registry authentication failure: fail without uploading.
• Duplicate immutable version: registry returns conflict; do not overwrite it.
• Partial workspace failure: return non-zero and do not claim complete success.

Test and evidence map

Run the focused checks with:

bun run docs:contracts:check
bun test scripts/docs-contracts.test.ts
cd packages/zig && zig build test