gnomonlearn
Docs/Grammar extraction and conformance gaps

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

  1. 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.
  2. Resolve the remaining test-decl contract conflict. Keep the authored EBNF-to-PEG translation, generated-file drift, and pinned Peggy validation green as grammar sources change.
  3. Decide the fixture schema, add a .gnm fixture 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.
  4. 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.