Skip to content

The Lock File

The methods.lock file records the exact resolved versions, tree digests, and semantic fingerprints for all remote dependencies. It makes installs verifiable — every developer and CI system can prove it fetched the same bytes, carrying the same meaning, that the original resolution saw.

What It Looks Like

["github.com/mthds/document-processing"]
version     = "1.2.3"
digest      = "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
fingerprint = "7c9e2b4f8a1d3e5c7b9f2a4d6e8c1b3f5a7d9e2c4b6f8a1d3e5c7b9f2a4d6e8c"
source      = "https://github.com/mthds/document-processing.git"
commit      = "8f5b2c1a9d3e7f4b6a8c2e5d1f9b3a7c4e6d8f2b"

["github.com/mthds/scoring-lib"]
version     = "0.5.1"
digest      = "sha256:e5f6a7b8c9d0e5f6a7b8c9d0e5f6a7b8c9d0e5f6a7b8c9d0e5f6a7b8c9d0e5f6"
fingerprint = "2d4f6a8c1e3b5d7f9a2c4e6b8d1f3a5c7e9b2d4f6a8c1e3b5d7f9a2c4e6b8d1f"
source      = "https://github.com/mthds/scoring-lib.git"
commit      = "3a7c4e6d8f2b8f5b2c1a9d3e7f4b6a8c2e5d1f9b"

Each entry records a package address, the exact resolved version, the tree digest of the fetched files, the semantic fingerprint of what those bytes mean, the HTTPS clone URL, and the commit the version tag pointed to when it was locked.

Why the Lock Is Regenerable

Version resolution is Minimum Version Selection: the resolved versions are fully determined by the manifests and the published version tags — a newer release never changes the answer, and no registry has to be consulted. The lock file can therefore be regenerated from the manifests plus the fetched sources, and regeneration reproduces the same entries as long as the repositories' published version tags — which tags exist, and which commits they point at — have not changed. It is a verification record — proof of what was fetched and what it meant — not the thing that decides versions. (go.sum plays the same role next to go.mod.)

File Location

The lock file must be named methods.lock and placed at the package root, alongside METHODS.toml. It should be committed to version control.

Locked Package Fields

Field Description
version The exact resolved version (valid semver).
digest The tree digest of the fetched package's files (sha256: followed by 64 hex characters) — what was fetched.
fingerprint The library crate fingerprint of the dependency's resolved content (64 lowercase hex characters) — what it means. Stable across reformatting; moves exactly when the dependency's effective type surface, prompts, or entry points change.
source The HTTPS clone URL the package was fetched from. Ends with .git.
commit The commit SHA the resolved version tag pointed to at lock time. A tag can be re-pointed; the commit cannot — it is the provenance record and the honest cache key.

The tree digest and the fingerprint are two different questions answered side by side: did I fetch the same bytes? and does it still mean the same thing? A dependency update whose fingerprint is unchanged changed nothing a consumer can observe; one whose fingerprint moved can be shown as a semantic diff before you adopt it.

Which Packages Are Locked

  • Remote dependencies (those without a path field) are locked, including all transitive remote dependencies.
  • Local path dependencies are NOT locked. They are resolved from the filesystem at load time and are expected to change during development.

How the Digest Is Computed

The digest is the package's tree digest: the SHA-256 of a listing that holds one line per file of the package, sorted by path, each line being what sha256sum prints for that file. The files are those the package's folder holds in the commit its version points at, read from git exactly as committed and filtered by the same rules that decide which files travel with any method, so the digest is the same on every machine and anyone can recompute it with git and coreutils.

A lock written before standard 7.0.0 records a hash instead of a digest. Such a lock is refused when it is read, with a message saying it predates tree digests: run mthds package lock to regenerate it. Its old hashes are never checked, so nothing is reported as tampered with.

When the Lock File Updates

The lock file is regenerated whenever the manifests change or a tool re-locks:

  • mthds package lock — resolves all dependencies from the manifests and writes the lock file.
  • mthds package add — records the new dependency's latest version as its floor in METHODS.toml, then re-locks.
  • mthds package update — raises the floors in METHODS.toml to the latest available versions, then re-locks, showing what moved. Under MVS nothing moves without a manifest edit — updating is a deliberate gesture, not a side effect of installing.

Verification

When installing from a lock file, the tool:

  1. Locates the fetched or cached package directory for each entry.
  2. Recomputes the tree digest of the package's files.
  3. Compares the computed digest with the lock file's digest field.
  4. Rejects the installation if any digest does not match — a hard failure, never a warning.

Deterministic Output

Lock file entries are sorted by package address (lexicographic ascending) to produce clean version control diffs.

See Also