gnomonlearn

RFC-0012 · Gnomon Tooling

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.

Status Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release.

View the generated reference catalog →

Read design questions and decisions →

Status: Draft Owners: DX, Compiler

1. Scope

Defines the canonical tooling surface for Gnomon: the formatter (gnomon fmt), compiler flags, CI integration requirements, and the language server protocol contract. This RFC governs the developer experience layer; it does not define language semantics (RFC-0008) or the annotation system (RFC-0011).

Tooling defined here MUST be consistent with the language grammar (RFC-0008 §8) and MUST NOT introduce behavior that contradicts any normative statement in the RFC suite.

2. Goals

  1. One canonical source representation for every valid .gnm file — no style debates, no configuration drift
  2. AI-authored and human-authored files are indistinguishable in canonical form
  3. Compiler internals (desugar pass, symbol table) are inspectable for debugging and conformance testing
  4. CI enforcement is normative and defined by this RFC, not left to project convention
  5. The language server provides a consistent, spec-derived authoring experience across all editors

Linked References

The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.

3. Invariants

  1. gnomon fmt MUST produce identical output for any two .gnm files with the same semantic content, regardless of original formatting.
  2. gnomon fmt MUST be sugar-preserving: it MUST NOT desugar source files. The canonical formatted form is the human-readable source, not the IR.
  3. gnomon fmt MUST NOT change the semantic meaning of any declaration.
  4. The --print-desugared flag MUST produce the exact AST that the compiler passes to the semantic analysis phase. Any divergence is a compiler defect.
  5. Every MCP tool and AI agent that writes .gnm files MUST pipe output through gnomon fmt before writing (RFC-0009 §6.4).
  6. gnomon fmt --check MUST be a required CI step. Failure to enforce this in CI is a project governance violation.

4. gnomon fmt: Canonical Formatter

gnomon fmt is the single canonical formatter for all .gnm source files. It is non-configurable and deterministic: for any valid .gnm input, gnomon fmt produces exactly one output. There are no configuration files and no per-project options.

4.1 Design Commitments

  • Non-configurable. No .gnomon-fmt.yaml, no per-project options. One canonical form across all projects and teams.
  • Sugar-preserving. @SensitiveData remains @SensitiveData. Bare fields remain bare fields. The formatter works on the parse tree before desugaring.
  • Idempotent. gnomon fmt applied twice produces the same result as applied once.
  • Total. gnomon fmt MUST handle every syntactically valid .gnm file, including files with only partial declarations. It MUST NOT refuse to format a valid file.

4.2 Canonical Property Ordering

Within any declaration body, gnomon fmt enforces the following property ordering. Properties of the same group may appear in any relative order within the group; gnomon fmt preserves source order within each group.

GroupPropertiesApplies to
1@ decoration lines (above the keyword line, alphabetical by facet name)all declarations
2annotations { } blockall declarations
3meaning, purposeall declarations
4is, flowentity, type, facet
5includesentity, type, facet (semantic composition)
6fields { } block, bare field declarationsentity, type, facet
7actor, preconditions, effects, mustSatisfyaction, invariant
8requiredEvidence, allowedStatus, policies { }agent, claim
9states, transitions, rulesflow
10input, outputs, returnsaction, query
11show, explain, actions, layout, data, forview
12provider, name, digest, version, parameters { }, rolesmodel
13ruleCompiler, promptTemplatecompiler block (project.gnm only)
14audience, version, includes (bundle entries)app, project
15examplesall declarations

Unrecognized properties are preserved at the end of the block in source order. gnomon fmt emits warning F12700 for each unrecognized property it encounters.

4.3 Formatting Rules

  • Indentation: 2 spaces per level. Tabs are converted to 2 spaces.
  • Trailing commas: always present on the last item in multi-line ident-set and string-seq values.
  • Blank lines: exactly one blank line between top-level declarations. No blank lines inside a declaration body. gnomon fmt MUST remove intra-body blank lines to produce canonical output. (Formatter Invariant 1 requires identical output for semantically identical content; preserving optional blank lines would violate it.)
  • String quoting: double quotes only. Single-quoted strings are normalized to double quotes.
  • Doc comments: /// lines are placed immediately above their declaration with no blank line between the last /// line and the declaration keyword.
  • Decorator lines: one @FacetName per line, alphabetical, no blank lines between decorators or between the last decorator and the declaration keyword.
  • Line length: no hard limit. Long string values are not reflowed.
  • Trailing newline: every file MUST end with a single newline character.
  • Compiled-rule comments: //compiled: and //compiled-by: structured comments immediately following a rule "..." statement MUST be preserved verbatim and MUST remain on the line(s) immediately after the rule statement with no intervening blank lines (RFC-0008 §11.3).
  • Epistemic modifiers: draft, deprecated, experimental, sealed, and abstract modifiers are formatted as part of the declaration header line, before the declaration keyword. gnomon fmt --check in CI MUST NOT suppress or hide epistemic modifier presence; they are visible in formatted output.

4.4 CLI Interface

gnomon fmt [options] [path...]

Options:
  --check       Exit non-zero if any file differs from canonical form; do not write files
  --diff        Print unified diff of proposed changes without writing
  --stdin       Read from stdin, write canonical form to stdout
  --verify      Exit 0 if file is already in canonical form, exit 1 if not; read-only (no file modifications). For pre-commit hooks and local checks.

Exit codes:
  0   All files are already canonical (or --check passed, or --verify passed)
  1   Formatter encountered a syntax error (file is not valid .gnm); also exit 1 in --verify mode if file is not in canonical form
  2   Files differ from canonical form (--check mode only)

path may be a file, directory (recursive), or omitted (formats all .gnm files in the project from project.gnm root).

4.5 CI Enforcement

gnomon fmt --check MUST be a required step in every project CI pipeline. Exit code 2 MUST fail the CI build. This is a normative requirement, not a recommendation.

Formatter violations are not compiler diagnostics (M08xxx range). They use the F prefix:

  • F12700: Unrecognized property encountered during formatting (warning, file is still formatted)
  • F12701: File does not end with a newline (auto-corrected by gnomon fmt, exit code 2 for --check)

4.6 AI Authoring Contract

Every MCP tool, AI agent, or automated process that produces .gnm file content MUST pass that content through gnomon fmt before writing to disk or returning it to the user. This is a normative requirement from RFC-0009 §6.4. A file written by an AI tool that is not in canonical form is a compliance violation of the AI authoring contract.

5. Compiler Flags

5.1 --print-desugared

Emits the post-desugar AST to stdout before semantic analysis. The output format is the canonical block form of the grammar (RFC-0008 §8) with all sugar forms expanded. This flag is the primary tool for:

  • Verifying that a sugar form expands as expected
  • Debugging desugar pass behavior
  • Generating input for conformance test fixtures (RFC-0008 §8)

The output MUST be valid .gnm source that passes gnomon fmt --check without modification.

5.2 --print-symbol-table

Emits the unified symbol table after semantic analysis to stdout in a structured format (JSON or YAML as specified by --format). Useful for tooling that needs to inspect declaration resolution.

5.3 --print-annotation-map

Emits the resolved annotation map for every declaration after the annotation merge pass (RFC-0011 §5). Output includes the source of each annotation value (inline, decorator, aspect) for traceability.

5.4 --format

Specifies the output format for --print-* flags. Values: json (default), yaml.

6. Grammar Conformance CI

The normative EBNF grammar in RFC-0008 §8 MUST be extracted as a standalone PEG grammar file and validated in CI. This section defines the CI contract.

6.1 Extraction

A CI step MUST extract all ebnf code blocks from RFC-0008 §8 (and RFC-0011 §4 for the annotation extensions) into a single canonical grammar file: grammar/gnomon.peg. This file is a derived artifact; the source of truth is the RFC text.

6.2 Validation

The extracted grammar MUST be validated by a PEG parser generator on every RFC commit. Validation fails if:

  • Any production rule is syntactically invalid
  • Any production references an undefined non-terminal
  • The grammar is ambiguous (where PEG ambiguity detection is available)

6.3 Conformance Test Fixtures

Each non-trivial grammar production MUST have at least one successful conformance fixture: a concrete .gnm snippet paired with its expected canonical AST. Failing fixtures MUST pair a .gnm snippet with expected diagnostics and require rejection. Fixtures live in grammar/fixtures/. The CI pipeline MUST:

  1. Extract the grammar
  2. Validate the grammar
  3. Run successful fixtures through the extracted grammar and compiler, compare their canonical ASTs to the expected AST, and assert no errors
  4. Run failing fixtures through the appropriate grammar or compiler stage, compare the expected diagnostics, and assert rejection

A production without a fixture fails the CI build (warning in draft status, error in accepted status).

7. Language Server Protocol (LSP) Contract

Do not implement from this section. RFC-0017 is the sole normative specification for the LSP contract. This summary is retained for historical context only.

Superseded. The normative LSP contract has been extracted into RFC-0017: Gnomon LSP Contract. RFC-0017 is the authoritative specification for all gnomon lsp behavior including completions, hover, diagnostics, the rule compiler feedback loop, and model-aware editing.

RFC-0012 retains responsibility for the gnomon fmt formatter, compiler flags, and CI enforcement. RFC-0017 takes responsibility for all gnomon lsp behavior.

The summary below is retained for orientation; see RFC-0017 for normative detail.

The Gnomon language server (gnomon lsp) provides editor integration. Required capabilities:

CapabilitySummary
textDocument/completionContext-aware property, identifier, model, and annotation completions
textDocument/hoverDeclaration kind, meaning, visibility, model binding, compiled rule expression
textDocument/definitionResolve any QUALIFIED reference, model reference, or import path
textDocument/diagnosticsAll compiler M-codes; async rule compiler diagnostics
textDocument/formattingApply gnomon fmt (identical output to CLI)
textDocument/codeActionCasing fixes, missing meaning, rule migration, model configuration
Rule compiler feedbackGhost annotation showing compiled constraint expression; Accept/Convert/Edit gestures

See RFC-0017 for the full normative contract.

Diagnostics

The diagnostic catalog for this RFC is authored in the structured Lean module and rendered in reference catalog § Diagnostics. Inline mentions in the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog at render time.

9. Security and Authorization

  1. gnomon fmt MUST NOT execute any code from the formatted file. It is a pure syntactic transformation.
  2. --print-* flags MUST NOT execute any user-defined code or invoke any runtime component.
  3. AI authoring contract enforcement (§4.6) is a normative security requirement: unformatted AI-authored files bypass the canonical form guarantee and may obscure malicious content differences from human reviewers.

10. Compatibility and Migration

  1. Changing the canonical property ordering (§4.2) is a breaking change to gnomon fmt and MUST increment the formatter version.
  2. Adding new properties to the ordering table is a non-breaking change; unknown properties are placed at the end.
  3. Adding new compiler flags is a non-breaking change.
  4. Changing the output format of --print-* flags is a breaking change.