gnomonlearn
Docs/RFC-0014 lockfile proposal

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.

  • Make module.lock a 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 update is 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

  1. Reconcile §§6–7, §9, §10.1–2, and §11, plus the M01401/M01404 definitions. Align the module.lock example, Lean term/grammar/invariants, and the lockfile domain projections; regenerate references and Turtle.
  2. Add deterministic serialization fixtures: identical inputs produce byte-identical lockfiles across runs; dependency ordering and serialization are canonical.
  3. Test a newly published compatible version against an existing locked build: the build retains its pinned version until gnomon update runs. Test a changed manifest, constraint violation, missing artifact, and digest mismatch with their exact diagnostics.
  4. Run source-bound RDF and public-site link checks and review any changed lockfile or diagnostic facts before release.