gnomonlearn
Docs/Independent framework frontend adapter evidence

Independent framework frontend adapter evidence

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: proposal and integration blocker evidence. Owners: Compiler, Language, DX, and framework release maintainers. Canonical AST stage and identity remain pending in the existing AST proposals. This document selects neither.

Actual producer boundaries

The framework has two distinct pipelines:

  1. graph/packages/graph-module-compile/node/module-compiler.ts loads module.graph.yaml with parseYaml. It compiles the graph-module YAML contract, not RFC-0008’s .gnm language.
  2. lean/lean/Gnomon/Lang/Parser.lean independently parses .gnm into Gnomon.Lang.Common.File. Check.lean, macro expansion, and entity SQL emitters consume that generic block model. The existing Bazel parser/corpus tests exercise this frontend, but no typed authored AST/source export or conformance CLI endpoint was found in the inspected sources.

The second is the appropriate independent frontend to integrate. Its present output is insufficient for the handwritten parsed-AST/source expectations. An adapter cannot recover discarded syntax or locations from this tree. Running the spec’s Peggy adapter inside the compiler adapter would compare the proposal parser with itself and does not solve this producer gap.

Reproducible native probe

audit_framework_frontend.py (repository access required) imports the actual framework parser through a small Lean serialization harness. It extracts unchanged sources from immutable local Git objects and verifies their SHA-256 values against the protobuf pin (repository access required). The current pin is framework commit 4a7fa0fda365466b94c51c45faf6020f3c993543 and leanprover/lean4:v4.30.0-rc2. Compiler invocation resolves the checked Lean binary once; temporary working directories cannot select a different Elan default toolchain. Only three small frontend modules and the probe are compiled, without Bazel, Cargo, mathlib, network downloads, or edits in the framework.

python3 tools/audit_framework_frontend.py \
  --framework-root ../gnomon \
  --output /tmp/gnomon-native-frontend-audit.textproto \
  --baseline tools/proposals/framework-frontend-history/914b9ecede705e11a909ef7895f38649a8415b41/audit.textproto \
  --comparison-output /tmp/gnomon-native-frontend-comparison.textproto
python3 -m unittest discover -s tools/tests -p 'test_framework_frontend.py'

framework_frontend.proto (repository access required) owns the native generic-tree observations and report. NativeFile transparently mirrors the existing producer model; it is not the proposed ParsedFile, canonical AST, or a successful conformance StageResult. Source digests bind immutable input snapshots, while SOURCE_MAPPING_UNAVAILABLE explicitly records the lack of independent comment/range artifacts. The harness does not import the generated grammar, Peggy, proposal lowering, or fixture expectations.

The current 35-input report (repository access required) produced 17 native accepts, 18 native rejections, and no runtime failures. These are observations, not passing fixtures. All three proposal-negative inputs were accepted by the legacy frontend. Of 32 positive inputs, 14 were accepted and 18 rejected. Annotation rejections use the actual older frontend’s M11803 text; other failures remain actual error text, without invented stable codes or byte ranges.

Fourteen focused native tests establish structure, progress, and losses independently from the proposal parser. In particular, each of these pairs produces the same native tree even though the missing syntax or documentation matters to the authored contract:

First inputSecond inputNative loss
query Q() -> core.Valuequery Q -> core.ValueParentheses discarded
query Q() -> core.Valuequery Q() - > core.ValueContiguous arrow distinction discarded
config-set core.x = trueconfig-set core.x trueAssignment = discarded
import "雪"Unterminated import "雪String closure not retained or rejected
config C {}Leading /// plus config C {}Documentation discarded

draft internal query Q {} becomes generic kind draft, name internal, and header tokens query Q; typed modifier/declaration roles are not established. variant E {} is accepted as an arbitrary kind despite lacking a current top-level authored production. Conversely, annotations, structured module operation lists, and some config literals fail before an adapter can emit the required candidate tree. Ordinary comments, byte ranges, and doc ownership are not present in the producer API.

Runtime progress correction and preserved baseline

In the historical framework commit 914b9ecede705e11a909ef7895f38649a8415b41, rule-expressions.gnm stalled at its authored division slash. In that pinned lexer, the non-comment / branch calls lexIdent "" on the same slash; slash is not an identifier character, so the remainder is unchanged. Recursion repeated without consuming input. The original bounded probe recorded a process failure (observed SIGXCPU), not a language rejection or partial successful AST. Inputs are isolated with a two-second CPU limit and ten-second wall deadline; an individual stall cannot erase the remaining observations.

framework_lexer_progress.patch (repository access required) was applied exactly and committed in its owning framework repository as 4a7fa0fda365466b94c51c45faf6020f3c993543. The branch now consumes the slash and retains .ident "/". Actual framework lexer/parser guards passed, including the new slash tokenization and division parse guards. The framework’s lean/tools/frontend-progress/evidence/progress.textproto records the actual source, driver, fixture, native export, and log hashes for that verification. This routine source-progress correction chooses no operator precedence, numeric type, canonical identity, or AST stage.

The original report and pin are preserved under an immutable historical path. Source, fixture, original driver, and harness hashes were validated when archived. --pin can reproduce that old producer without overwriting the baseline; its stall remains a runtime failure rather than a language rejection.

The protobuf observation comparison (repository access required) binds both reports by digest. 34 observations are unchanged; only the rule-expressions.gnm invocation failure becomes a native file result. Every fixture’s bytes, the export harness, Lean version, runtime limits, and other three pinned source hashes are identical. Only the pinned lexer hash changes. The current generic tree retains the division slash, while the punctuation, comment, range, typed grammar, and source-preservation losses remain. Neither the native result nor equality of native observations is typed AST/source equality or compiler conformance.

Proposed adapter integration contract

Use a thin adapter over a producer-owned typed export, not a second parser hidden in a transport shim. The pending stage decision determines the ultimate root descriptor. For the currently executable authored-stage proposal, the producer can prototype ParsedFile and the separate SourceArtifact under their existing proposal namespaces without announcing a canonical identity.

Integration requirementOwnerConcrete acceptance
Lossless lexical informationCompiler/LanguagePreserve required punctuation, string closure, exact literal spelling, comments, and UTF-8 ranges before building nodes; rejected syntax cannot collapse to the same token stream as successful syntax
Strict typed declaration/body parsingCompiler/LanguageAll 36 reviewed alternatives and recursive structures independently match the handwritten proposal ASTs; unknown forms refuse explicitly, without generic success
Independent source exportCompiler/DXProduce digest-bound comment/declaration ranges and safe doc-owner bindings from the compiler’s own lexical/parser provenance; match the six handwritten source expectations without calling the spec parser
Diagnostics and adapter failuresCompiler/LanguageStable approved codes and exact UTF-8 spans for language rejection; process/timeout/decode failures are transport failures, never fabricated M-codes
Comparison-stage and descriptor identityExisting Language/Compiler/DX decisionRecord the pending owner choice, review field assignments, publish the chosen descriptor, and pin its digest; no automatic promotion of proposal namespaces
Compiler invocation endpointCompiler/DXExpose one absolute-input-path adapter command that invokes the real frontend and emits binary protobuf StageResult; logs go to stderr; exit zero means a produced result, including rejection
Independent equality gateCompiler/spec maintainersParser and compiler adapters independently compare to the same handwritten canonical AST/diagnostic corpus through run_conformance_fixtures.py; source artifacts have a separate equality/integrity gate
Reproducible release/CI dependencyFramework/spec release ownersPublish the framework commit/archive or adapter executable, pinned toolchain and descriptors; configure private repository access and run both repositories’ gates from those immutable artifacts

The current observation harness uses protobuf text because the existing Lean producer has no generated typed/binary export. A future transport shim may decode producer-owned protobuf text and encode StageResult binary, but it must not fill missing nodes, defaults, ranges, diagnostics, or trivia by reparsing source with the proposal parser. Neither a generic NativeFile in Any nor a raw token/CST record satisfies the authored AST contract.

The framework’s current CLI graph compiler does not expose this Lean endpoint. These local probes are therefore deliberately separate from spec’s normative conformance job. CI integration requires the published/pinned framework producer and credentials; the local destination commit is not assumed publicly available.

Remaining normative gates

The spec proposal retains 175/180 productions across all 36 bare declaration forms. The five unreachable productions remain WHITESPACE, query-shorthand, nat-lang-stmt, nat-lang-block, and qualified-set; native observation counts do not change that inventory or resolve those grammar gaps. Documentation attachment ambiguities, CommonMark diagnostics, complete formatter maps, known authored grammar inconsistencies, semantic implementation, and independent typed compiler emission remain open.

grammar/fixtures/ still has no approved canonical corpus, and check_fixture_envelopes.py --require-corpus remains red. Probe success means evidence was collected; it is not language or compiler conformance.