gnomonlearn
Docs/Transform expression contract decision

Transform expression contract decision

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: proposed. Owner: Compiler and specification maintainers. No authored RFC rule, Lean catalog, diagnostic, or implementation changes are made here.

Observed conflicts

  1. RFC-0021 §§1, 2, 6, and 9 promise that every accepted transform returns a non-error output for every input. Section 6.3 instead accepts a denominator that may be zero with warning M21114 and says evaluation returns an error. The two rules cannot both hold. The same proof obligation must cover modulo, conversions, substring bounds, numeric overflow, and any non-finite float behavior admitted by the final value model; grammar finiteness alone proves only termination.
  2. RFC-0021 §§2–3 and 9 call TEL a strict subset of RFC-0008 §11, but that section describes visibility and epistemic state. RFC-0008 §6.32 is the actual transform authoring site: apply { fieldName = expr }, evaluated against source. RFC-0021’s only binding is input, the old value of one field. A whole-entity source expression cannot be parsed as TEL as written.
  3. RFC-0021 §7 assigns specific M21xxx errors after ratification and narrows M01603 to unknown language version. RFC-0016 §§2.4, 10, and its diagnostic catalog still assign M01603 to non-total referenced transforms, while RFC-0008 §6.32 assigns M16021 to non-total apply expressions. A compiler and its consumers cannot infer which diagnostic identity wins.
  4. RFC-0021 §§3, 5, 6.2, and 9 define a null literal, a Null bottom type, nullable inputs, and isNull(input). RFC-0006 §3 invariant 7 and §4.D say Gnomon has no null type or literal: an optional field is absent, not a present null value. RFC-0021’s current grammar cannot be a sublanguage of the published Gnomon value model as written. Its source-bound RDF nodes for Null, isNull, and null safety repeat the conflict.
  • Define TEL as the expression sublanguage inside RFC-0008 §6.32 apply assignments. Its environment contains a read-only source entity at the declared from version. A field-level transform may expose input only as an explicit alias for the selected source field; the compiler resolves the alias before checking and lowering. Document the field selection and reject ambiguous or missing selections. Update RFC-0021’s §11 cross-reference and RFC-0008/RFC-0016 references together.
  • Keep a single total TEL profile. Possible division or modulo by zero is a compile error. Define a proof rule for every partial primitive and reject any expression whose safety cannot be established, including unsafe conversions or substring bounds. Specify numeric domains and edge cases so the word “total” includes runtime behavior. If a partial profile is wanted, give it a separate name, type, and call-site contract in a later RFC; do not silently weaken ChangeType or apply.
  • Reserve M21xxx for expression-local parse, type, purity, and totality errors; keep M01603 for a referenced transform that fails the call-site totality obligation until an explicit versioned migration removes it. Keep M16021 for RFC-0008 apply totality failures during the same compatibility window. The compiler may attach an M21xxx cause to either enclosing diagnostic, preserving the legacy primary code for consumers. Publish exact precedence, source ranges, and the sunset version before changing primary codes.
  • Model optional old fields through presence refinement, not a null value. A transform can test isPresent(source.field) or an equivalent declared presence predicate. In the present branch the compiler narrows the field to its non-optional type; an absent branch must explicitly produce a valid value of the new output type or be rejected. Remove null, Null, and isNull from TEL unless a future RFC introduces a first-class optional value type across the core type system. Align M21107 with unguarded access to an absent optional input. This keeps the RFC-0006 boundary rule intact.

Acceptance and migration evidence

  1. Amend the three authored RFCs and their Lean/diagnostic catalogs in one change; regenerate reference and RDF artifacts, and pass drift checks.
  2. Test each primitive on boundary values and a rejected unproved case; test whole-entity source and field-level input examples against the parser, type checker, and runtime. A successful compile must never yield an error value on a valid input under the published numeric and string domains.
  3. Publish a code-by-code table for M01603, M16021, and M21xxx, including severity, primary/causal relationship, compatibility period, and downstream consumer migration. Inventory existing emitted and persisted diagnostics.
  4. Reconcile the RFC-0021 QA answers only after source and implementation evidence satisfy these checks. Collection transforms remain unsupported until a separate compiler-owned extension has its own totality rules.
  5. Test an optional source field present and absent, a required source field, nested optional field access, and a deliberately invalid null literal. Verify flow-sensitive refinement and M21107 against the same parser and type checker used for migration execution.