gnomonlearn

RFC-0014 · Module Versioning Protocol

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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →


Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.


1. Motivation

RFC-0001 defines the Gnomon module system and the imports block in module.gnm. RFC-0005 defines the install plan that resolves and materializes module dependencies at build time. Neither RFC establishes a normative versioning scheme for Gnomon modules: there is no formal definition of what constitutes a breaking change, no canonical import syntax for expressing version constraints, no deterministic resolution algorithm, and no lockfile contract.

Without these, the following failure modes occur in practice:

  • A downstream module silently adopts a breaking upstream change because no version constraint was expressed.
  • Two independent consumers of a shared module pin different incompatible versions, producing divergent behavior that only surfaces at runtime.
  • CI passes on developer machines because local caches hold a previously-resolved version that differs from what a clean build would resolve.

This RFC closes those gaps by specifying: the version format, the definition of a breaking change, import constraint syntax, the resolution algorithm, the module.lock lockfile contract, associated compiler diagnostics, and the gnomon update CLI command.


2. Scope

This RFC covers:

  • Semantic version format for Gnomon modules.
  • Normative definition of breaking, minor, and patch changes.
  • Version constraint syntax in module.gnm imports.
  • Deterministic transitive dependency resolution.
  • The module.lock lockfile format and CI enforcement.
  • Compiler diagnostics in the M014xx range.
  • The gnomon update CLI surface.

This RFC does not cover: module publication workflow, registry authentication, or private registry configuration. Those are deferred to a future RFC.


3. Version Format

Gnomon module versions follow Semantic Versioning 2.0.0: MAJOR.MINOR.PATCH, where each component is a non-negative integer with no leading zeros.

1.0.0
2.14.3
0.1.0   # pre-1.0 modules: any change MAY be breaking

Pre-release labels (e.g. 1.0.0-alpha.1) are permitted and sort below the release version per SemVer spec. Build metadata (e.g. +build.42) is allowed but ignored for resolution purposes.

3.1 Component Semantics

ComponentIncrement when
MAJORA breaking change is introduced (see §4).
MINORNew public surface is added in a backward-compatible way, or an existing type is widened.
PATCHA non-semantic change is made: documentation edits, formatting, whitespace, or rule-text rewrites that produce byte-for-byte identical compiled expressions.

A MAJOR increment resets MINOR and PATCH to 0. A MINOR increment resets PATCH to 0.


4. Breaking Change Definition

A change is breaking if 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.

The following changes are always MAJOR:

  1. Removing a public declaration. Deleting an exported entity, flow, rule, type alias, or constant.
  2. Renaming a public declaration. Changing the identifier of any exported symbol, unless the old identifier is retained as an alias pointing to the new name.
  3. Narrowing a field type. Replacing a field’s type with a strict subtype (e.g. String → Email, Number → PositiveInt), or adding a validation constraint to an existing field.
  4. Adding a required field to an existing entity. Any new field without a default value on a publicly exported entity type.
  5. Invalidating existing flow state values. Removing or renaming a state in a public flow, or removing a transition such that a state value that was reachable under version N is no longer reachable or becomes a compile error under version N+1.
  6. Changing the arity or parameter types of a public rule or function in a way that breaks existing call sites.

The following changes are always MINOR:

  • Adding a new optional field (with a default) to an existing exported entity.
  • Adding a new exported declaration (entity, flow, rule, constant, type alias).
  • Widening a field type (e.g. Email → String).
  • Adding a new state or transition to a public flow without removing existing ones.
  • Adding a new optional parameter with a default to a public rule.

The following changes are always PATCH:

  • Editing documentation comments (/// or /** */).
  • Reformatting source with no change to the compiled output.
  • Rewriting rule expressions that produce identical compiled bytecode or IR.
  • Updating internal (non-exported) declarations without affecting the public surface.

5. Import Syntax

Version constraints are expressed in the imports block of module.gnm (RFC-0001 §4). The constraint is a string literal following the version: key.

imports {
  "com.example.hr"      version: "^1.2.0"
  "com.example.audit"   version: "~2.3.1"
  "com.example.core"    version: "1.0.0"
}

5.1 Constraint Operators

SyntaxNameMeaning
"^1.2.0"CompatibleSame MAJOR, >= 1.2.0. Equivalent to >=1.2.0 <2.0.0.
"~1.2.0"Patch-compatibleSame MAJOR.MINOR, >= 1.2.0. Equivalent to >=1.2.0 <1.3.0.
"1.2.0"ExactExactly version 1.2.0. No other version satisfies this constraint.

For modules with MAJOR = 0, the ^ operator treats MINOR as the breaking component: ^0.2.0 means >=0.2.0 <0.3.0.

Omitting a version: key is a compile error (M01402). Unconstrained imports are not permitted.


6. Version Resolution

6.1 Algorithm

Resolution is deterministic and follows a highest-satisfying-version strategy:

  1. Starting from the root module, collect all direct and transitive imports declarations, building a dependency graph.
  2. For each unique module ID, collect the set of version constraints placed on it by all importers.
  3. Determine the set of versions available for that module (from the configured registry).
  4. Select the highest available version that satisfies all constraints simultaneously. If no such version exists, emit M01403.
  5. Write the fully resolved graph to module.lock.

This strategy is analogous to npm’s semver resolution. It prefers recency while guaranteeing that all expressed constraints are met.

6.2 Circular Dependencies

A circular version dependency — where module A requires module B which requires module A — is a compile error M01400, regardless of version constraints. The compiler emits the full cycle path in the diagnostic message.

[M01400] Circular module dependency detected:
  com.example.hr -> com.example.payroll -> com.example.hr

6.3 Constraint Conflicts

If no single version of a module satisfies all collected constraints, the compiler emits M01403 and lists each conflicting constraint with its origin module.

[M01403] No version of "com.example.core" satisfies all constraints:
  ^1.0.0  required by com.example.hr@1.4.0
  ^2.0.0  required by com.example.audit@3.1.0

Resolution halts on the first unresolvable conflict. The developer must update one or more consumers to align their constraints before proceeding.


7. The module.lock Lockfile

7.1 Purpose

The lockfile records the exact resolved version of every transitive dependency. It ensures that all environments — developer machines, CI, production builds — use identical module graphs.

7.2 Format

module.lock is a UTF-8 text file in the root of the module source tree, adjacent to module.gnm. It is machine-generated and human-readable.

# module.lock — generated by Gnomon compiler. Do not edit by hand.
# Root: com.example.myapp@1.0.0
# Generated: 2026-04-29T14:00:00Z

[[dependency]]
id      = "com.example.hr"
version = "1.4.2"
digest  = "sha256:a3f1..."

[[dependency]]
id      = "com.example.core"
version = "1.9.0"
digest  = "sha256:7bc2..."

[[dependency]]
id      = "com.example.audit"
version = "3.1.4"
digest  = "sha256:d401..."

Each [[dependency]] entry records:

  • id: the canonical module identifier.
  • version: the exact resolved version string.
  • digest: a SHA-256 content digest of the resolved module artifact, for integrity verification.

7.3 VCS and CI Requirements

module.lock MUST be committed to version control. It is not a build artifact; it is a source artifact.

CI MUST fail if the lockfile is stale. A lockfile is stale if re-running resolution against the current module.gnm and registry state would produce a different lockfile. The compiler detects staleness by re-resolving and comparing; a mismatch emits M01401.

[M01401] Lockfile is stale. Run `gnomon update` to regenerate module.lock.

This enforcement pattern mirrors the CI contract established in RFC-0012.


8. Compiler Diagnostics (M014xx)

This RFC introduces two diagnostic code ranges: M01400–M01499 (compiler diagnostics emitted during gnomon build) and M14800–M14899 (lint diagnostics emitted during gnomon lint --semver). Both ranges are owned by RFC-0014. Codes from these ranges MUST NOT be allocated by other RFCs.

Note: RFC-0014 lint diagnostics use the M148xx sub-range rather than an L-prefix, as the L-prefix is allocated exclusively to RFC-0017 per RFC-0000 §6.2.

Governance note: The L01400–L01499 lint code range self-allocated by this RFC requires formal registration in RFC-0000 §6.2. Until that registration is complete, L01400–L01499 codes MUST NOT be emitted by any implementation. The M01400–M01499 and M14800–M14899 compiler diagnostic ranges defined in this section remain valid and do not require additional allocation; they fall within the M014xx prefix assigned to RFC-0014 in RFC-0000 §6.2.

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

Diagnostics M01400–M01404 are fatal: compilation does not proceed past the resolution phase if any are present.

8.1 Lint Diagnostics (M148xx)

The following codes are emitted by gnomon lint --semver rather than by the compiler. They are not compiler diagnostics and do not affect compilation; they gate the publish workflow.

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

9. The gnomon update CLI

gnomon update re-runs version resolution, selects the highest available version satisfying all current constraints, and rewrites module.lock.

gnomon update                  # Update all dependencies within existing constraints.
gnomon update com.example.hr   # Update a single dependency within its constraint.
gnomon update --major          # Allow resolution to select higher MAJOR versions,
                             # updating constraints in module.gnm accordingly.

gnomon update --major is the only operation that modifies module.gnm directly. Before doing so it emits a summary of the proposed constraint changes and requires --confirm or interactive confirmation unless --yes is passed.

Running gnomon update in a clean environment with no registry access and no cached artifacts emits M01403 for any unresolvable module.


10. Invariants

  1. Determinism. Given the same module.gnm, module.lock, and registry state, the compiler always produces the same resolved module graph.
  2. Lockfile authority. When module.lock is present and not stale, it is the sole source of truth for resolved versions. The registry is not consulted for version selection during a locked build.
  3. No implicit upgrades. The compiler never silently selects a version outside the expressed constraint range. A constraint violation is always a hard error.
  4. Alias preservation. A renamed public declaration is not breaking if and only if the original identifier is retained as a compile-time alias. The alias must be marked @deprecated and may be removed in the next MAJOR version.

11. Failure Modes

ScenarioOutcome
Circular dependency in the import graphM01400, compilation halts.
Stale lockfile in CIM01401, build fails.
Missing version: on an importM01402, compilation halts.
Constraint conflict between transitive dependenciesM01403, compilation halts.
Registry artifact digest mismatchM01404, compilation halts.
Developer runs gnomon update with no network and cold cacheM01403 on unresolvable modules; cached modules resolve normally.
Breaking change published under MINOR version bumpM14800 from gnomon lint --semver, blocking publish.
Non-breaking change published under MAJOR version bumpM14801 from gnomon lint --semver (warning; publish not blocked).
Pre-release version selected without opt-inResolver skips pre-release; M01403 if no non-pre-release satisfies constraint.
Module published with a breaking change under a MINOR bumpDownstream consumers may receive unexpected compile errors; no automated protection — publisher discipline and semver linting tooling (future RFC) are the mitigation.