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-rootnow consistently namesproject.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-executioncapability 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
- Record the owner choices for formatter equivalence, decorator form, and CI flag/exit codes in RFC-0012’s companion Q&A.
- 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.
- 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.
- 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.