gnomonlearn
Docs/Module import syntax decision

Module import syntax 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: proposal for owner decision. No normative RFC text or compiler behavior has changed.

Source conflict

  • RFC-0001 §4 defines each import key as a lowercase module FQN and each value as a quoted version constraint. Its examples use gnomon.core: "^1.0.0".
  • RFC-0008 §8.19 gives the grammar module-import-entry ::= FQN ":" STRING and uses the same form in its example.
  • RFC-0014 §5 instead shows "com.example.hr" version: "^1.2.0" and says that omitting the version: key emits M01402. This is a different token sequence and does not conform to the RFC-0008 grammar.
  • The 62 module.gnm manifests in the staged Lean corpus use the FQN: "constraint" form. The current Lean frontend parses their generic structure but does not resolve imports or enforce constraint syntax.

Keep FQN: "constraint" as the canonical syntax. It agrees with the module RFC, the language grammar, and the staged corpus. Revise RFC-0014 §5’s example and its M01402 description to say that an import without a quoted constraint value is invalid. Keep ^, ~, and exact SemVer constraints as RFC-0014 defines them. Do not silently accept the alternate RFC-0014 example syntax: doing so would introduce a second authoring grammar without a specified precedence or migration rule.

The alternative is to adopt "FQN" version: "constraint". That would require an explicit RFC-0001 and RFC-0008 grammar change, migration of all 62 staged manifests, and compatibility behavior for existing authored modules. There is no observed implementation or consumer need for that additional form.

Acceptance after decision

  1. Align all three RFC clauses, grammar, examples, and M01402 wording.
  2. Test exact, compatible, and patch-compatible constraints; reject a missing or malformed constraint with a stable diagnostic.
  3. Validate each staged manifest and a deliberately malformed fixture using the same parser that the CLI, Bazel rule, and bundle compiler consume.
  4. Keep resolved versions and digests in module.lock per RFC-0014; syntax validation alone does not satisfy dependency resolution or lockfile drift.