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 eitherdigestorversion. 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
ModelRefcomment in §10.2 instead allows both and saysdigesttakes precedence. - RFC-0018 Lean statement
b13says both “Exactly one” and “digest takes precedence.” Those clauses cannot both apply to a validModelRef. - The inherited RFC-0018 claim
https://gnomon.sh/claim/RFC-0018/sec-8/model-digest-or-versionrepeats the both-present precedence rule. RFC-0017’s M08795 quick fix says to adddigestorversionwhen 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
- 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.
- 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.
- 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.
- 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.