Module Dependency Lock File

The lock file (invowkmod.lock.cue) records the exact versions of all resolved module dependencies, ensuring reproducible builds across machines and over time.

It is auto-generated by invowk module sync and invowk module update.

Example Lock File

version: "2.0"
generated: "2025-01-10T12:34:56Z"

modules: {
    "https://github.com/example/common.git": {
        git_url:          "https://github.com/example/common.git"
        version:          "^1.0.0"
        resolved_version: "1.2.3"
        git_commit:       "abc123def456789012345678901234567890abcd"
        alias:            "common"
        module_id:        "io.example.common"
        namespace:        "common"
        command_source_id: "common"
        content_hash:     "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    }
}

Root Fields

Field	Description
version	Lock file format version (current: "2.0")
generated	Timestamp when the lock file was created
modules	Map of module keys to locked module entries

Module Entry Fields

Each entry in modules contains:

Field	Description
git_url	Git repository URL
version	Original version constraint from invowkmod.cue
resolved_version	Exact resolved version
git_commit	Commit SHA for the resolved version (re-verified whenever the same version is resolved again)
alias	Namespace alias (if set)
path	Subdirectory path (if set)
module_id	Canonical module identity parsed from invowkmod.cue
namespace	Computed display namespace for compatibility
command_source_id	Source ID used when publishing commands for execution/disambiguation
content_hash	SHA-256 content hash of the module tree (re-verified whenever the same version is resolved again, whether or not the module is cached)

Module Keys

The key in the modules map is derived from the Git URL and optional path:

modules: {
    "https://github.com/example/monorepo.git#modules/io.example.cli.invowkmod": {
        git_url: "https://github.com/example/monorepo.git"
        path:    "modules/io.example.cli.invowkmod"
    }
}

Lock keys preserve the source declaration identity. The parsed module_id is stored separately and is used for canonical local cache and vendor directory names such as invowk_modules/io.example.common.invowkmod. Different source keys that resolve to the same module_id are rejected as canonical module collisions instead of overwriting each other.

Usage Notes

• Commit invowkmod.lock.cue to version control for reproducible builds.
• invowk module add writes the lock file automatically (no need to run invowk module sync afterward).

Integrity Checks During Sync

When invowk module sync, add, update, or tidy resolves a module to the same resolved_version that the lock file already records, Invowk checks that the remote reproduces the locked entry:

• The fetched commit must equal git_commit. A different commit means the upstream tag was re-pointed, and sync fails with a locked-commit mismatch.
• The module content must hash to content_hash. This applies on a fresh machine or CI runner with an empty module cache, as well as to modules already cached. A fresh copy that fails the check is removed from the cache.

In both cases the lock file is not rewritten.

When a module resolves to a different version, because you changed its constraint or invowk module update found a newer match, the old entry's commit and hash are not applied. The new version's values become the next baseline. A module with no lock entry yet is recorded on its first sync with a warning that it has no integrity baseline.

A v1.0 lock file records no content hashes, so its entries cannot detect tampering. Discovery and invowk module vendor reject vendored modules backed by such entries, and sync fetches a fresh copy instead of trusting the cache. Run invowk module sync once to upgrade the lock file to v2.0.

If an upstream re-tag or content change is intentional, run invowk module remove <git-url> and then invowk module add the module again. That records a new baseline without editing the generated lock file by hand. If you suspect the local cache was modified instead, delete the module's cache directory named in the error.

Common Workflows

# Resolve and lock
invowk module sync

# Commit the lock file
git add invowkmod.lock.cue
git commit -m "Lock module dependencies"