gnomonlearn
Docs/RFC-0008 source file discovery proposal

RFC-0008 source file discovery 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: proposed first-release decision. Owners: DX and Compiler. No Gnomon installation is deployed, so this is a source and compiler cutover rather than a live data migration.

Conflict and current evidence

RFC-0008 §§4-5 and §10.1 require concept-named .gnm files. Section 7 instead discovers only fixed class filenames such as schema.gnm and actions.gnm, warning M07902 and skipping other files. Its table has no filename for several declared kinds, including Relations, model, transform, workflow, api, and serve; it also puts mutations.gnm under Operations while §§3 and 6.21 classify mutation as Schema. RFC-0001 and RFC-0033/0034 contain further fixed-filename instructions. The checked-in Gnomon sample corpus has 253 .gnm files under lean/savvi, including 58 schema.gnm, 54 queries.gnm, 53 actions.gnm, and 62 module.gnm. The spec examples instead use 13 concept-named declaration files plus project.gnm.

Use concept-named source files. Keep project.gnm at the project root and module.gnm in each module folder as reserved manifests. Within a module folder, discover all other .gnm files, parse their top-level declarations, and enforce the existing one-class-per-file rule from the parsed declarations. Keep class and declaration-kind validation in the canonical registry, not in a filename table. Apply §10.1’s NAME and non-generic-name rules to the file stem. A file with an unsupported declaration or mixed classes must receive a location-aware error; it must never be silently skipped. Explicit manifest file lists, where present, take precedence as specified by RFC-0001.

This admits new declaration kinds without changing the discovery algorithm and allows an owner to split a large class across concept files. It also requires renaming the current fixed-name sample corpus and updating Bazel inputs, manifests, CI fixtures, and any tooling that assumes a fixed basename. M07902’s current “unrecognized filename, skip file” meaning must be retired or reassigned before release; do not reuse its identity for a different error without updating the Lean diagnostic catalog and all consumers.

The alternative is to make the fixed filename table canonical. That would preserve most checked-in examples, but it requires extending the table for every declaration kind, resolving duplicate class/filename mappings, and rewriting §§4-5 and §10.1’s concept naming rule. It also restricts each module folder to one file per fixed role.

Acceptance

  1. Amend RFC-0001, RFC-0008, RFC-0033, and RFC-0034 to one discovery and naming rule; align their Lean statements, diagnostic catalog, RDF facts, and generated references.
  2. Implement folder discovery, explicit-list precedence, class validation, deterministic file order, and a hard diagnostic for unsupported source content. Assert that no valid .gnm file is silently omitted.
  3. Rename sample files, regenerate build inputs and lockfiles, and run parser, compiler, Bazel, proof, projection, and site gates. Refresh source-bound reviews invalidated by the authored changes.