gnomonlearn
Docs/RFC-0018 model pin contract proposal

RFC-0018 model pin contract 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 requested, 2026-10-04. Owners: Language, Compiler, DX, and Spec. No Gnomon compiler is deployed, so no stored model declarations need conversion.

Conflict

  • RFC-0008 §6.20 requires provider, name, and either digest or version. Its grammar note in §11 requires exactly one of the two pin properties and rejects duplicate singleton properties.
  • RFC-0018 §8 lists both properties as optional with a one-of requirement. Its ModelRef comment in §10.2 instead allows both and says digest takes precedence.
  • RFC-0018 Lean statement b13 says both “Exactly one” and “digest takes precedence.” Those clauses cannot both apply to a valid ModelRef.
  • The inherited RFC-0018 claim https://gnomon.sh/claim/RFC-0018/sec-8/model-digest-or-version repeats the both-present precedence rule. RFC-0017’s M08795 quick fix says to add digest or version when neither is present; it does not settle the both-present case.

The current Gnomon framework checkout has no gnomon-compiler implementation of this DSL to use as conformance evidence. This is a normative source decision, not a migration from a deployed compiler.

Recommendation

Use exactly one pin. A content digest and a provider version are different identity schemes; accepting both creates an unused, potentially contradictory field and makes cache and hover identity dependent on implicit precedence. The compiler should reject a model declaration containing both with an explicit diagnostic, alongside the existing M08795 for neither. A ModelRef should carry one tagged pin (digest or version) in the compiler API; if its language-neutral spelling retains two optional fields, validation must still enforce exclusive-or before use. Cache provenance must record the selected pin and resolved content digest when available.

The alternate choice is to allow both and define digest precedence. That requires changing RFC-0008 §11 and its grammar/validation rules to accept both, while specifying how version mismatch, hover, cache keys, and provider resolution behave when both are supplied. The existing RFC-0018 wording does not define those cases.

Acceptance after the owner chooses

  1. Align RFC-0008 §6.20/§11, RFC-0018 §8/§10.2, the relevant Lean statements and invariant summaries, and RFC-0017’s pin diagnostic guidance.
  2. Keep claim and domain subject IRIs stable while updating the RFC-0018 projection literal; regenerate Turtle from the protobuf source. Re-review every source-bound verdict affected by the RFC-0018 and RFC-0008 Lean or prose hashes. Compare the exact RDF triple diff and local claim queries.
  3. Add compiler parsing/validation fixtures for neither, digest only, version only, both, and duplicate properties once the compiler implementation is present. Check rule-cache identity and hover output for each accepted pin.
  4. Regenerate reference catalogs and run the corpus, Lean, projection, link, query, and release diagnostic gates. Do not describe a clean source gate as compiler conformance until the implementation fixtures pass.