lpm.lockb format reference

lpm.lockb is a legacy generated companion to lpm.lock. It stores a subset of metadata from lockfile versions before 13.

lpm.lock is always the authoritative install input. When a lockfile carries TOML-only metadata that lpm.lockb cannot represent, LPM CLI skips the binary write and removes any stale lpm.lockb from a previous install.

Lockfile version 13 does not write lpm.lockb. LPM CLI removes a stale binary file when it writes the current lockfile.

For a repository that still has a legacy binary file, mark it as binary in .gitattributes:

.gitattributes

lpm.lockb binary

File location

<project-root>/lpm.lockb

Layout (v3)

[Header: 16 bytes]
  magic              [u8; 4]  = b"LPMB"
  version            u32 LE   = 3
  package_count      u32 LE
  string_table_off   u32 LE   — byte offset where the string table starts

[PackageEntry × N: 36 bytes each, sorted by name]
  name_off           u32 LE   — offset into the string table
  name_len           u16 LE
  version_off        u32 LE
  version_len        u16 LE
  source_off         u32 LE   — 0 = None
  source_len         u16 LE
  integrity_off      u32 LE   — 0 = None
  integrity_len      u16 LE
  deps_off           u32 LE   — offset into the deps table
  deps_count         u16 LE
  tarball_off        u32 LE   — 0 = None  (v2+)
  tarball_len        u16 LE                (v2+)

[DepsEntry × total_deps: 6 bytes each]
  str_off            u32 LE   — offset into the string table
  str_len            u16 LE

[ProvenanceEntry × M: 68 bytes each, sparse]
  package_index       u32 LE   — index into PackageEntry table
  publisher           (u32 off, u16 len)
  workflow_path       (u32 off, u16 len)
  workflow_ref        (u32 off, u16 len)
  cert_sha256         (u32 off, u16 len)
  subject_name        (u32 off, u16 len)
  subject_sha512      (u32 off, u16 len)
  log_id              (u32 off, u16 len)
  bundle_sha256       (u32 off, u16 len)
  integrated_time     u64 LE
  rekor_log_index     i64 LE

[ProvenanceFooter: 8 bytes]
  magic              [u8; 4]  = b"PRV3"
  evidence_count     u32 LE

[String table]
  packed UTF-8, no NUL terminators

All numeric fields are little-endian. Packages are sorted by their package identity so reads can binary-search the entry table. The provenance section is sparse: packages without verified evidence do not pay a 68-byte per-package cost.

Wire-format version

Current reader format: v3 (BINARY_VERSION). This binary version is independent from TOML lockfile version 13.

The binary reader rejects any file whose header version is not exactly BINARY_VERSION — strict by design. Layout differs across versions, so interpreting one version as another could produce garbage or drop security evidence. lpm.lock remains the authoritative input; the next compatible write_all rewrites lpm.lockb as the current version.

Sentinel for optional fields

Optional string fields (source, integrity, tarball, and the optional provenance identity fields) use (off=0, len=0) to mean None.

To keep this sentinel unambiguous, the writer rejects empty strings at insert time: an empty source URL, integrity hash, or tarball URL is nonsensical input regardless. Failing loud is correct.

What's NOT stored in the binary lockfile

The binary format is intentionally smaller than the TOML format. These fields are not represented:

alias-dependencies — npm-alias edges
importers — manifest snapshots used by frozen installs
workspace-packages — content-addressed workspace union rows and importer projections
patches — patch paths and patch-file SHA-256 records
root-aliases — root-level npm-alias map
ambient-peer-installs — root-level auto-installed peer links
peers — per-package resolved peer pinning
catalogs — catalog protocol snapshots
auto-isolated-peer-conflicts — linker orchestration state
os / cpu / libc / optional / node-engine — platform, optional-reachability, and dependency engine state
registry-signatures / registry-published-at — npm registry signature evidence
instance-id — exact package-instance identity
dependency-targets / peer-targets — exact edge targets
root selection instance-id — exact root target

Lockfile version 13 always takes the TOML-only path. LPM CLI skips the binary write and removes any stale binary file.

Verified provenance itself is supported by v3. If the same project also uses frozen-install importer snapshots, npm aliases, peer pinning, dependency engine constraints, platform-specific optional packages, catalogs, or registry signatures, seeing only lpm.lock is still correct.

Reading the file

The reader BinaryLockfileReader mmaps the file once, parses the header, validates the magic + version, and exposes by-name lookup via binary search over the entry table. No allocation per entry; string slices borrow directly from the mmap.

LPM CLI can read a valid legacy binary file. Current installs read the authoritative TOML lockfile for the exact graph.

lpm.lockb format