gnomonlearn
Docs/RFC-0012 formatter and tooling proposal

RFC-0012 formatter and tooling 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: fixture outcome contract approved on 2026-10-05; other first-release decisions remain proposed. Owners: DX and Compiler. Nothing is deployed, so these are source and artifact contract choices.

Fifteen previously unreviewed RFC-0012 claim/domain nodes now have source-bound projection verdicts: eight match the authored and Lean sources, and seven preserve the formatter-equivalence, decorator-layout, or CLI-mode conflicts described below. No RDF triple was changed by this review.

Canonical output and semantic equivalence

RFC-0012 §3.1 requires byte-identical output for any two .gnm files with the same semantic content. The same section requires preservation of syntactic sugar. Section 4.2 preserves source order among properties in the same group; §4.3 preserves doc comments and structured //compiled: comments. Two files can therefore have the same runtime meaning but retain different sugar, property order, or comments after formatting. Lean statement b9 and the RDF claim fmt-deterministic repeat the broad semantic-equivalence rule.

Recommend: define the formatter as a deterministic, idempotent function of the parsed concrete source, modulo the explicit normalization rules in §4. Inputs that differ only in normalized whitespace, quoting, or other specified formatting details must produce byte-identical output. Do not promise identical output for arbitrary semantically equivalent programs. Keep the independent requirements that formatting preserves meaning and does not desugar source. Specify whether preserving the relative order of same-group properties is part of the contract, then test that choice with two valid inputs whose fields are reordered. The alternative is a semantic canonicalizer, which would have to reorder all commutative constructs, discard or normalize comments, and choose a single spelling for each sugar form; it conflicts with the authored sugar-preserving design.

Decorator form

RFC-0011 §4.5 requires multiple annotation facets to format as one sorted @[FacetA, FacetB] group. RFC-0012 §4.2 and §4.3 instead require one sorted @FacetName line per facet. The first contract is consistent with RFC-0011’s grouped syntax and its merge-order description. These are different bytes for the same input and cannot both be the canonical form.

Recommend: use RFC-0011’s grouped form for multiple facets, preserve a single @FacetName, and amend RFC-0012’s ordering table and formatting rule. This is contingent on the RFC-0011 grammar decision in RFC0011_ANNOTATION_CONTRACT_PROPOSAL.md. Test single decorators, multiple lines, grouped input, alphabetical sorting, and a second formatting pass.

CI command and exit codes

RFC-0012 §3.6 and §4.5 require gnomon fmt --check in every project CI and reserve exit code 2 for noncanonical input. The companion Q&A calls gnomon fmt --verify ./... the canonical CI use, returning exit code 1 for a format difference. The RFC currently defines both flags with overlapping read-only behavior, and --verify also uses code 1 for syntax errors.

Recommend: make --check the sole canonical CI flag, with exit 0 for canonical input, 1 for syntax error, and 2 for formatting difference. Remove the --verify contract and correct the Q&A. A pre-commit hook can call --check. This leaves one stable machine-readable result for every CI outcome. If --verify is retained as an alias, it should share --check’s exit codes; the Q&A must not assign it a separate CI contract.

Projection and implementation gaps

  • The RDF claim path-default-project-root now consistently names project.gnm, matching RFC-0012 §4.4 and its source-bound review. The subject and predicate IRIs remain stable.
  • RFC-0012 §4.5 names F12700 and F12701. Lean also defines F12702 and F12800–F12802. The RDF F12702 claim adds an unsupported once-per-file emission count; the F127x and F128x range claims are not established by the authored prose. Add explicit diagnostic and range text, or narrow those claims to what the authored RFC and Lean actually say.
  • RFC-0012 §6’s extracted grammar and pinned parser validation are implemented. The approved fixture outcomes and protobuf envelope schema are implemented; canonical AST messages and compiler fixtures remain open.
  • RFC-0012 §7 is historical context; RFC-0017 is the sole normative owner of LSP behavior. RDF claims and domain facts representing LSP behavior need a provenance review so they do not imply RFC-0012 is its current owner.
  • The RDF gnomon.fmt.no-execution capability now summarizes the §9 no-execution guarantee. The approved correction removes the former claim that every print flag is a pure syntactic transformation: §5.2 emits a symbol table after semantic analysis and §5.3 emits a post-merge annotation map. The capability IRI remains unchanged.

Acceptance

  1. Record the owner choices for formatter equivalence, decorator form, and CI flag/exit codes in RFC-0012’s companion Q&A.
  2. Align RFC-0012, RFC-0011, the Lean statements and diagnostics, RDF source claims and domain facts, generated catalogs, CLI documentation, and site. Preserve stable IRIs when only a literal changes.
  3. Test canonical output, idempotence, meaning preservation, sugar retention, decorator grouping, comments, same-group property order, syntax errors, and CI exit codes against a single formatter implementation.
  4. Resolve the grammar fixture format and implement the RFC-0012 §6 gate. Refresh source-bound proof and projection reviews after normative edits, then run corpus, diagnostic, RDF, site, and first-release integration gates against the same pinned source revision.

Approved fixture outcome contract (2026-10-05)

The owner selected expected canonical ASTs for successful inputs and expected diagnostics for failing inputs. Positive fixtures must compare parser and compiler ASTs and require no errors; negative fixtures must compare specified diagnostics and require rejection. A raw Peggy return value is not a canonical AST. Authored §6.3, Q&A, Lean, and RDF projections now reflect this outcome distinction. Protobuf fixture envelopes and an executable comparison runner are implemented. Canonical language AST messages, real compiler adapters, and authored fixtures remain implementation work. Cross-stage records use protobuf under repository instructions. The former Q&A prescription of JSON expectations was retired when the approved paired protobuf envelope contract was integrated. Canonical language AST ownership and real adapters remain outstanding.

Fixture envelope implementation (2026-10-05)

proto/conformance_fixture.proto defines the authoring envelope with a successful concrete AST Any or stage-specific expected diagnostics. grammar/fixtures/README.md documents paired .gnm and .expected.textproto authoring. check_fixture_envelopes.py compiles and validates the schema, rejects unresolved AST types and invalid input paths or byte ranges, and fails an empty corpus with --require-corpus. It does not run the compiler or establish production coverage. Canonical AST messages, parser and diagnostic adapters, executable fixtures, and the compiler gate remain outstanding.

Comparison runner implementation (2026-10-05)

tools/run_conformance_fixtures.py invokes parser and compiler executables through the protobuf StageResult contract. It compares concrete AST messages with repeated-field order preserved, checks exact ordered rejection diagnostics, and requires parser acceptance before an expected compiler rejection. Adapter process failures and timeouts fail the run. Both envelope validation and runner load imported descriptors independently of serialization order.

The runner rejects unknown coverage names and can require all authored productions with --require-full-coverage. Its instrumentation contract excludes speculative matches discarded by backtracking. Eighteen runner tests and fifteen envelope tests pass, including a real subprocess transport test using a test-only AST and adapters. No language conformance corpus exists yet; these tests establish runner behavior, not RFC-0008 compiler conformance.

Approved no-execution projection correction (2026-10-05)

The owner approved narrowing the RDF capability summary to the authored no-user-code-execution guarantee. The IRI is unchanged. The summary no longer mischaracterizes symbol-table or post-merge annotation output as purely syntactic. This changes one literal, without changing RFC or Lean requirements.