Skip to content

M0030 contract-snapshot

Rule: A contract crate exports its version and keeps every version's schema snapshot in git, unchanged once in the base.

Code M0030 (stable, never reused)
Id contract-snapshot
Category workspace
Source spirit_level
Fix by hand
Needs the crate map ([map] or map-file)

Level per tier

Tier Level Reason
small off
small-workspace off
medium off
big deny every party of a contract knows its version and what that version looks like; a released snapshot never changes
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
const string "VERSION" the integer constant of the library root that holds the contract's version
snapshot string "schema/v{version}.json" the snapshot of a version, in the crate's directory; {version} is the number
base string "main" the branch work merges into; a snapshot it has must not change

Why

A contract crate holds the types that cross a process or node boundary, and every party links it. Parties are built and deployed at different times, so each must know which version of the contract it speaks and what that version looks like. The version constant answers the first; the schema snapshot of each version, kept in git, answers the second and lets a test check that a reader still reads what an older writer wrote. A snapshot that changes after it reached the base branch breaks that promise silently: a party built against it now reads something else under the same number.

The crates are the ones the crate map marks contract = true.

crates/foo_wire/
  src/lib.rs          pub const VERSION: u32 = 2;
  schema/v1.json      the schema of version 1, unchanged since it landed
  schema/v2.json      the schema of version 2

How to fix

  • No version: add pub const VERSION: u32 = 1; to the library root (parameter const names it).
  • No snapshot: write the schema of the current version to schema/v<N>.json (parameter snapshot) and commit it. A test that generates the schema from the types and compares it with the file keeps it current.
  • Not in git: commit the snapshot.
  • A snapshot changed against the base (parameter base): restore it, bump VERSION, and write the new schema to the next version's file. Readers tolerate unknown fields, so adding a field is a new version, not an edit.

Configure

[lints.contract-snapshot]
level = "deny"
const = "VERSION"
snapshot = "schema/v{version}.json"
base = "main"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(contract-snapshot) <reason> (waivers); the code works there too, as in [lints.M0030].