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:a1b2c3d4e5f6..."
    }
}

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
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 cached module tree (tamper detection)

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).

Common Workflows

# Resolve and lock
invowk module sync

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