Grammar extraction and conformance gaps
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: source extraction, structural checks, EBNF syntax/reference validation, and a compiling generated PEG with focused probes implemented; compiler-backed fixture coverage remains open. Owner: DX and Compiler. This document records observed source and CI state; it does not assert compiler conformance.
Observed source boundaries
RFC-0008 calls §8 “Normative EBNF Grammar” and places its 38 ebnf blocks
there. Section 9 is “Unified Declaration Model” and contains no ebnf
blocks. RFC-0011 §4 now adds four ebnf blocks. RFC-0008 §8.0 and RFC-0012 §6
previously pointed extraction at §9; those authored references, Lean
catalogs, RDF facts, and generated catalogs now point to §8. Historical
normalization spikes retain their original input text as provenance.
tools/check_grammar_sources.py extracts all 42 blocks from the actual
sections to grammar/gnomon.ebnf. The output records the
RFC and source line for each block. CI checks byte drift against the authored
Markdown. This intermediate EBNF bundle feeds the derived
grammar/gnomon.peg artifact.
tools/check_grammar_catalog.py now checks that each of those 42 authored
blocks appears byte-for-byte in its RFC’s Lean grammar catalog. RFC-0008’s
catalog has all 38 §8 blocks, plus the field-decl fragment authored in §6;
RFC-0011’s catalog has its four §4 blocks. The gate detects missing or stale
Lean fragments whenever the authored EBNF changes.
The extracted source contains one query-decl definition after removing an
illustrative duplicate from RFC-0008 §8.21. The owner approved a single
integrated top-level-decl rule and one nonempty decorated-decl rule;
the two RFC-0011 extension placeholders and duplicate decorator rule were
removed. The eleven open-body declaration kinds named in RFC-0008 §6.0 now
admit annotation-block, with a source-bundle gate checking every binding.
The RFC-0011 decorator contract is also recorded in
RFC0011_ANNOTATION_CONTRACT_PROPOSAL.md.
RFC-0011 §4.4 states the exact eleven-kind inline annotation scope and
excludes unbraced or expression-only forms.
The approved RFC-0046 configuration forms are now in RFC-0008 §8.18 as
Schema-class config and restricted override-file config-set
productions. Their source and Lean grammar blocks are included in the catalog
gate; compiler fixtures and actual .gnm parser conformance remain open.
RFC-0008 §8.12 also defines given/when/expect tests, while RFC-0013 requires
given/when/then tests and a different invocation model. The authored
contract, Lean, diagnostics, and fixtures cannot converge until the owner
selects one model. See
RFC0013_TEST_CONTRACT_PROPOSAL.md.
The notation table calls this an ISO 14977 subset, but the blocks also use
character classes, set subtraction, and postfix repetition. tools/emit_peg.py
translates these forms, inserts lexical spacing, prioritizes literal-led
alternatives before generic identifiers, and checks output drift. Peggy 5.1.0
is pinned in package-lock.json; tools/check_peg.py compiles the grammar
and runs 18 focused syntax probes. This validates the generated PEG with a
parser generator, but does not prove every intended parse or runtime AST.
The first Peggy compile exposed RFC-0011’s immediately left-recursive
annotation-predicate ::= annotation-predicate "and" annotation-predicate.
RFC-0011 §4 now defines a nonempty chain of annotation-predicate-atom
values. It accepts the same conjunction strings and permits a finite PEG
parse. The Lean grammar catalog and source-bound review hashes were refreshed;
the prior review verdicts and findings remain in place.
tools/check_grammar_syntax.py parses every extracted production in the
authored dialect, checks grouping and alternatives, and rejects unresolved
production references. It found that RFC-0008’s module-op-entry used an
undefined BOOL token. RFC-0008 §8.1 and its Lean grammar catalog now define
BOOL ::= "true" | "false"; UNICODE_CHAR remains an explicit prose-defined
builtin. The bundle now has 180 productions and zero syntax or reference
problems. The gate and its malformed-source regression tests run in spec CI
and the direct release command. This validates expression structure only;
it does not determine PEG precedence, lexical spacing, AST shape, or parser
behavior.
python3 tools/check_grammar_structure.py now counts the extracted
productions and rejects duplicate names, literal ... extension
placeholders, and missing annotation-block bindings for the eleven open-body
kinds. The strict release gate reports zero structural problems. This gate
does not parse the EBNF dialect, validate a PEG, or run compiler fixtures;
those obligations remain open.
An earlier RFC-0008 edit changed only the illustrative query duplicate and
clarified its shorthand expansion. Its single normative query-decl production
and shorthand acceptance are unchanged. The later annotation edits integrate
the top-level rule and all eleven open-body forms. The catalog reconciliation
added the remaining RFC-0008 §8 blocks to Lean. Lean evidence, the extracted bundle,
diagnostic inventories, and source-bound review hashes were refreshed from
the revised sources; existing projection and proof verdicts retain their
earlier semantic findings. The pinned external Lean corpus compiled and
emitted 55 RFC catalogs after the change.
npm run grammar:examples audits all 14 checked-in .gnm files under
narrative/examples; currently 0/14 parse with the derived PEG. The
first errors show inherited forms that differ from the current authored
grammar: type bodies with values, flow bodies with meaning before
states, a legacy action body, and an unquoted project name. The command
exits nonzero and is not counted as a passing conformance gate. Each example
needs an owner-reviewed migration or an authored grammar correction; the
current parser/compiler distinction must also be resolved before attributing
every failure to example source alone.
The project example also conflicts with RFC-0008’s own illustrative manifest
and §8 grammar on modules punctuation and several body fields. The exact
source comparison and decision criteria are in
PROJECT_MANIFEST_CONTRACT_PROPOSAL.md.
Focused PEG probes now make the grammar’s present behavior explicit without
claiming that the manifest contract has been reconciled.
The repository still has no broad grammar/fixtures/ conformance suite or
canonical AST/diagnostic comparison against the framework compiler. RFC-0012 §6.3 expects canonical AST
fixtures. Historical Q&A text prescribed JSON diagnostic expectations; that
prescription was retired when the owner approved ASTs for successful fixtures
and diagnostics for failing
fixtures. Protobuf envelopes and the adapter comparison runner are implemented;
canonical language AST messages and real adapters remain open as described in
RFC0012_FORMATTER_CONTRACT_PROPOSAL.md.
The current framework gnomon-compile target wraps a YAML graph-module
compiler, not an RFC-0008 language parser. Its former .gnm YAML source
files now use .graph.yaml; the compiler still calls parseYaml. Using
that target for DSL fixtures would test the wrong language. The
source-format boundary record inventories
the approved and locally implemented filename cutover. The older Lean .gnm
parser now rejects RFC-0011 annotation syntax with M11803, and its 253-file
parse corpus passes. It remains a permissive structural parser rather than
the required RFC-0008/0011 conformance implementation.
Acceptance before normative release
- Keep §8 grammar-source references aligned across RFC-0008, RFC-0012, Lean, RDF claims, generated catalogs, and source-bound reviews. Preserve stable claim IRIs where only their values change.
- Resolve the remaining
test-declcontract conflict. Keep the authored EBNF-to-PEG translation, generated-file drift, and pinned Peggy validation green as grammar sources change. - Decide the fixture schema, add a
.gnmfixture for every non-trivial production, compare the expected AST or diagnostics as specified, and run each fixture through the compiler. Enforce draft/accepted severity policy. - Run extraction, PEG validation, fixture coverage, fixture parsing, and compiler conformance in both spec and compiler CI. Require all five in the normative release gate and pin the generated artifact in site publication.
Probe execution inventory (2026-10-05)
node tools/check_peg.mjs --coverage traces the eighteen existing probes.
Successful inputs enter 80 and match 38 of the 180 authored productions.
The command lists never-entered and never-matched rules to guide fixture
implementation. Failed probes do not contribute. Matches can be discarded
by backtracking, so this is execution evidence, not accepted-tree,
alternative, AST, or compiler conformance coverage.
The owner approved AST expectations for successful fixtures and diagnostic
expectations for failing fixtures. The outcome distinction is integrated into RFC-0012, Q&A, Lean, and RDF.
The implemented protobuf envelopes and comparison runner are described in
grammar/fixtures/README.md. Canonical language AST design, compiler adapters,
accepted-parse coverage instrumentation, and executable language fixtures remain
open in RFC0012_FORMATTER_CONTRACT_PROPOSAL.md.
Accepted parse inventory
The syntax-only PEG now has retained-value provenance instrumentation in
tools/accepted_parse_coverage.mjs. Existing successful probes retain 39/180
authored productions. Backtracked alternatives and lookahead probes are
excluded, and unsupported semantic/value-discarding grammar constructs fail
closed. Six focused tests pass, including the actual generated grammar.
This supplies syntax instrumentation; canonical ASTs, adapter integration,
whole-grammar fixtures, and compiler conformance remain open.
Inline annotation execution matrix
The pinned PEG gate now runs 41 syntax probes. Eleven full-file probes cover each RFC-0011 inline-body binding, with accepted-parse instrumentation checking that the owning body rule, annotation-block, and inline-annotation survive backtracking. Six excluded forms reject an inline block while accepting the same declaration with the block removed: facet, relation, flow, compute, unbraced query, and config-set. Existing syntax probes remain in place. Successful accepted parses now retain 73/180 authored productions. This is syntax execution evidence; required semantic singleton checks, canonical AST fixtures, compiler adapters, and full production conformance remain open.
Configuration syntax execution
The PEG gate now runs 54 probes. Five positive configuration probes cover all nine config property slots, qualified overrides, nested literals, empty lists/maps, strings, booleans, and signed/decimal numeric syntax. Eight negative probes reject source references, calls, operators, null, unquoted map keys, trailing list/map commas, and boolean-token prefixes. The generated PEG drift check and all probes pass; accepted syntax coverage is 77/180. These probes leave required/singleton slots, flag/perTenant relationships, value/type compatibility, and the pending numeric type decision to compiler conformance. They are not canonical AST fixtures.
Module manifest syntax execution
The PEG gate now runs 62 syntax probes. Eight added module cases cover imports, objects, agents, string and structured operation entries, both Boolean rollback checkpoint values, and dependencies with or without a checkpoint. Negative cases reject quoted/prefixed Boolean values, missing paths, unknown properties, and non-string dependencies. The generated PEG drift check passes; accepted parses retain 84/180 authored productions. These checks verify authored syntax, not module dependency resolution, per-agent activation atomicity, rollback execution, canonical ASTs, or compiler conformance.
Executable typed AST proposal
The pending parsed-stage recommendation now has an executable protobuf schema
and generated-grammar lowering, with thirty-two handwritten AST expectations and
three proposal-local rejections. All 36 implemented declaration alternatives are
import, type, config, config-set, query, entity, facet, relation, flow, claim,
enum, action, mutation, actuator, procedure, event, task, compute, client, saga,
workflow, policy, invariant, aspect, compose, apply, extend, view, app, agent,
model, project, module, test, annotation facet, and annotation aspect.
Retained syntax provenance covers 175/180 productions in that separate
proposal corpus. Recursive types/literals,
modifier/property/decorator order, explicit false/omission, duplicate map keys,
and query sugar remain visible in typed messages; arrays/CST nodes are not
serialized as ASTs. Domain properties retain bare field sugar, optional/empty
blocks, and ordered transitions, policies, and enum values. Four rule kinds and
typed authored expressions are implemented without selecting operator
precedence. Operations have typed bindings, effects, retries, failure forms,
session preconditions, client return/error alternatives, and opaque foreign
script bodies. Typed control/composition structures retain step/compensation
keywords, handlers and terminal markers, policy slots, invariant parameters,
aspect targets/contributions, precedence lists, and apply/extend roles. View,
layout, app, agent, and model bodies retain optional target/widget/scope presence,
show commas, ordered entries, typed routes, and exact model parameters.
Manifests/tests/annotations preserve current grammar distinctions without
deciding pending import, test, filename, or RDF identity contracts. Unambiguous
leading docs now have source-artifact owner bindings; ambiguous doc ownership and
variants outside the current grammar still refuse explicitly.
The inventory, exact pending comparison-stage
decision, and acceptance criteria are in
grammar/proposals/parsed-ast-fixtures/README.md.
This does not approve a canonical language identity or supply the independent
compiler adapter. The canonical corpus and normative release gate remain open.
The candidate investigation also found that the generated PEG distinguishes
contiguous qualified names from spaced postfix selectors and rejects a
contiguous method call accepted with spacing before the dot. That lexical and
ordered-choice gap is documented for review rather than silently reinterpreted
by the typed adapter. Operation probes found that procedure preconditions
require two newlines in the generated parser and that the authored client
status-family alternative (4xx) is unreachable under its ordered choice.
The prototype records both gaps without changing the grammar contract. Opaque
scripts retain exact body text, and their internal comment matches cannot
establish Gnomon comment-production coverage.
The agent investigation also found that the authored and generated grammar
require readScope twice because both the property and its child block own the
keyword. The candidate’s fixture uses readScope readScope {} and a regression
records rejection of a single keyword. This contract inconsistency remains for
Language/Compiler review; no normative source is silently changed.
Five production names remain absent from accepted proposal fixtures:
WHITESPACE, the two legacy natural-language rules, qualified-set, and the separate
query-shorthand rule have no root-reachable caller. Ordinary line/block and
leading doc comments now have positive handwritten fixtures. A separate
digest-bound source artifact preserves exact
comments, top-level UTF-8 ranges, and unambiguous leading doc owner ordinals.
Coverage scope/reachability, remaining doc ownership and compiled metadata,
complete formatter maps, independent compiler emission, desugaring, and semantics
remain required before this candidate can become canonical conformance.