gnomonlearn
Docs/RFC-0014/Reference catalog

RFC-0014 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0014: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0014.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0014. Edit that source and regenerate this catalog.


Title: Module Versioning Protocol
Status: draft
Owners: Compiler, Platform
Diagnostic range: M01400-M01499

Proof citations in source: 10 / 10. Standalone proof verification is pending.


Definitions

TermMeaning
Breaking changeA change such that any module that compiled successfully against version N would either produce a compile error or exhibit a change in runtime behavior when compiled against version N+1.
Stale lockfileA lockfile that, if regenerated against the current module.gnm and registry state, would produce a different result.
module.lockA UTF-8 text lockfile in the module root recording the exact resolved version and SHA-256 digest of every transitive dependency.

Diagnostics

CodeSeverityDescription
M01400ErrorCircular module dependency detected.
M01401ErrorLockfile is stale; re-run gnomon update.
M01402ErrorImport declaration is missing a version: constraint.
M01403ErrorNo version satisfies all constraints for a given module.
M01404ErrorResolved module digest does not match lockfile entry (integrity failure).
M01410WarningImport constraint allows MAJOR upgrades (^ on 0.x module); consider pinning.
M01420WarningA direct dependency has a newer compatible version available.
M14800WarningBreaking change detected under MINOR or PATCH version bump; gnomon lint —semver blocks publish.
M14801WarningNon-breaking change published under MAJOR version bump; gnomon lint —semver warns but does not block publish.

Invariants

  1. A renamed public declaration is non-breaking only if the original identifier is retained as a @deprecated compile-time alias removable in the next MAJOR. (enforced by: compile-time)
  2. CI MUST fail when re-running resolution against the current module.gnm and registry would produce a lockfile differing from the committed module.lock. (enforced by: CI)
  3. Codes in M01400-M01499 and M14800-M14899 are owned by RFC-0014 and MUST NOT be allocated by other RFCs. (enforced by: governance)
  4. Given the same module.gnm, module.lock, and registry state, the compiler always produces the same resolved module graph. (enforced by: compile-time)
  5. The compiler never silently selects a version outside the expressed constraint range; constraint violation is always a hard error. (enforced by: compile-time)
  6. When module.lock is present and not stale, it is the sole source of truth for resolved versions and the registry is not consulted for selection. (enforced by: compile-time)
  7. module.lock MUST be committed to version control as a source artifact, not treated as a build artifact. (enforced by: CI)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Breaking Change Definition

  1. MUST — Changing arity or parameter types of a public rule or function in a way that breaks call sites must be a MAJOR version increment. (proof citation: rfc0014_b0_grounded; verification pending)
  2. MUST — Narrowing a field type or adding a required field must be a MAJOR version increment. (proof citation: rfc0014_b14_grounded; verification pending)
  3. MUST — Removing or renaming a public declaration must be a MAJOR version increment unless an alias is retained. (proof citation: rfc0014_b12_grounded; verification pending)

Compiler Diagnostics (M014xx)

  1. MUST_NOT — Codes in M01400-M01499 and M14800-M14899 must not be allocated by other RFCs.
  2. MUST_NOT — L01400-L01499 codes must not be emitted until formal registration in RFC-0000 §6.2 is complete.

Import Syntax

  1. MUST — Every import must declare a version: constraint; omitting it is M01402. (proof citation: rfc0014_b17_grounded; verification pending)

Invariants

  1. MUST — Resolution must be deterministic given the same module.gnm, module.lock, and registry state. (proof citation: rfc0014_resolution_deterministic; verification pending)
  2. MUST_NOT — The compiler must not silently select a version outside the expressed constraint range. (proof citation: rfc0014_b24_grounded; verification pending)
  3. MUST — When module.lock is present and not stale, it must be the sole source of truth for resolved versions. (proof citation: rfc0014_b5_grounded; verification pending)

The gnomon update CLI

  1. MUST — gnomon update —major must emit a summary and require confirmation before modifying module.gnm.

The module.lock Lockfile

  1. MUST — CI must fail if the lockfile is stale, emitting M01401. (proof citation: rfc0014_b8_grounded; verification pending)
  2. MUST — module.lock must be committed to version control.

Version Format

  1. MAY — Any change to a pre-1.0 module may be breaking.

Version Resolution

  1. MUST — Circular module dependencies must emit M01400 and halt compilation. (proof citation: rfc0014_b2_grounded; verification pending)
  2. MUST — The resolver must select the highest available version satisfying all collected constraints simultaneously.
  3. MUST — Unresolvable constraint conflicts must emit M01403 listing each conflicting constraint and its origin. (proof citation: rfc0014_b21_grounded; verification pending)

Linked References

(no cross-RFC dependencies)