RFC-0014 lockfile proposal
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Status: owner decision pending. Owners: compiler and platform. Nothing is deployed; the first release can define a clean lockfile format.
Contradictory authored requirements
RFC-0014 §7.2 includes # Generated: 2026-04-29T14:00:00Z in its
module.lock example. §7.3 defines staleness as any difference from
re-resolving against the current module.gnm and registry state, with M01401
on a mismatch. §6 selects the highest version satisfying all constraints.
Thus a newly published compatible module can make an otherwise valid committed
lockfile stale, and a fresh timestamp can change its bytes even when the
resolved graph is identical.
RFC-0014 §7.1 says the lockfile ensures identical module graphs across
environments, and §10.2 says a present, non-stale lockfile is the sole source
of resolved versions and the registry is not consulted for version selection
during a locked build. Those guarantees cannot hold with an unconditional
registry re-resolution in CI. §9 already gives gnomon update the explicit
operation that fetches newer satisfying versions and rewrites the lockfile.
Recommended first-release contract
- Make
module.locka deterministic serialization of the root identity, normalized direct constraints, and exact transitive dependency IDs, versions, and SHA-256 artifact digests. Exclude generated timestamps and other volatile metadata from normative bytes. - A locked compile reads the committed graph without selecting newer registry versions. It checks that the current manifest’s direct constraints are represented and that every pinned version satisfies all relevant constraints. It verifies fetched artifact bytes against the recorded digest. It emits M01401 for a manifest/lock mismatch or invalid locked graph and M01404 for a digest mismatch.
gnomon updateis the operation that consults the registry, selects the highest satisfying versions, and writes a canonical lockfile. CI may run an explicit update-check policy, but such a freshness policy is separate from the required reproducible locked-build check and does not silently rewrite pins.
The alternative is to require every CI run to select the latest compatible registry versions. That makes the lockfile a moving cache, weakens the locked-build guarantee, and requires a separate policy for timestamps and registry availability.
Acceptance after owner choice
- Reconcile §§6–7, §9, §10.1–2, and §11, plus the M01401/M01404 definitions.
Align the
module.lockexample, Lean term/grammar/invariants, and the lockfile domain projections; regenerate references and Turtle. - Add deterministic serialization fixtures: identical inputs produce byte-identical lockfiles across runs; dependency ordering and serialization are canonical.
- Test a newly published compatible version against an existing locked build:
the build retains its pinned version until
gnomon updateruns. Test a changed manifest, constraint violation, missing artifact, and digest mismatch with their exact diagnostics. - Run source-bound RDF and public-site link checks and review any changed lockfile or diagnostic facts before release.