Composition layer
Lockfile
How stax.lock ensures reproducible builds
stax.lock is the intended lockfile format for package resolution. The current reference CLI ships lockfile types and merge semantics, but does not yet write stax.lock automatically during stax build.
Goals
- Pin exact digests for every resolved package
- Make builds reproducible across environments
- Surface dependency conflicts early
Format
{
"lockVersion": 1,
"specVersion": "1.0.0",
"packages": {
"ghcr.io/myorg/packages/github-workflow:2.0.0": {
"digest": "sha256:abc...",
"dependencies": ["ghcr.io/myorg/packages/git-utils:1.0.0"]
},
"ghcr.io/myorg/packages/git-utils:1.0.0": {
"digest": "sha256:def...",
"dependencies": []
}
}
}Fields
| Field | Description |
|---|---|
lockVersion | Lock file format version |
specVersion | stax spec version used during resolution |
packages | Map of package references to their resolved digests and dependencies |
Each package entry contains:
| Field | Description |
|---|---|
digest | Exact OCI digest (e.g., sha256:abc...) |
dependencies | List of transitive package references |
CI Behavior
Lockfile-capable builders should fail in CI when stax.lock is out of date unless explicitly told to refresh it. This prevents unintentional dependency drift.
Automatic lockfile refresh is planned future work for the reference CLI.
Committing the Lockfile
The stax.lock file should be committed to version control. This ensures that all team members and CI environments resolve the same package versions.