Gnomon DSL and graph-module format boundary
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: first-release source-format decision approved; local YAML cutover
implemented in framework commit 25281b681. Owners: language/compiler,
graph-module build, and specification maintainers. No Gnomon deployment exists;
published package and external file consumers remain unverified.
Evidence
RFC-0008 §8 reserves .gnm for its keyword-driven Gnomon DSL. The extracted
framework checkout instead has 161 files under modules/modules/ with .gnm
extensions: 49 module manifests begin with apiVersion:, 111 other files
begin with name:, and one begins with type:. None begins with the RFC-0008
module, entity, type, annotation, or import forms. The checked-in
modules/modules/core/module.gnm begins apiVersion: graph.savvi.io/v1.
The current graph/packages/graph-module-compile pipeline sets
DEFAULT_MANIFEST_FILENAMES to module.gnm and calls parseYaml for the
manifest and object files. Its gnomon-compile Bazel target wraps that graph
module compiler. It validates a different source language from RFC-0008;
passing its tests does not prove the normative DSL grammar or annotation
semantics. A static search found no RFC-0008 top-level or decorator grammar
parser in the extracted framework or original Aion checkout outside the spec
tree. That search cannot prove that no parser exists in unpublished packages.
At least 32 non-.gnm files in gnomon/graph/packages/graph-module-compile,
gnomon/rules, gnomon/modules, and workflows reference .gnm paths or
discovery behavior. The corpus also contains relative references between
source files. A file
extension change therefore requires a graph-module consumer cutover, not just
renaming the files.
Recommended first-release boundary
Reserve .gnm for the RFC-0008 language. Rename the existing YAML graph
module corpus to .graph.yaml, with module.graph.yaml as its manifest name,
and keep the graph-module compiler a separate, explicitly named YAML pipeline.
Move source paths with Git history preserved, update relative object paths,
discovery defaults, Bazel rules, package contents, tests, and documentation in
one reviewed cutover. No deployed data needs conversion, but inspect any
published module archive and external package consumers before dropping their
old filename contract.
Implement an RFC-0008 parser and compiler under a distinct language target.
Generate and validate grammar/gnomon.peg from the authored EBNF dialect with
a pinned parser generator, then exercise source fixtures and diagnostics
against that implementation. The current graph-module YAML compiler must not
be counted as the RFC-0008 conformance runner.
Local cutover evidence
The framework renamed 213 YAML graph-module files to .graph.yaml: 161 under
modules/modules, 35 under vocab/modules, 13 under integrations/modules,
and four under web/test-data. It updated discovery, Bazel inputs, relative
references, fixtures, package sources, and generated schema references. All
213 files parsed as YAML, and their relative .graph.yaml paths resolved.
The focused graph compiler and model tests passed; bazel build @modules//:bundle --remote_cache= compiled the core source closure. The 267
.gnm keyword DSL examples under lean/savvi and
spec/narrative/examples remain .gnm. This local source cutover does not
establish an RFC-0008 DSL compiler or validate published consumers.
Acceptance
- The owner approved distinct source-format identities and the first-release filename choice. Inventory published graph-module archives and exact-path consumers; record any compatibility period needed for those artifacts.
- The 213 tracked YAML sources were renamed and local compiler and build references updated. Build the published graph-module packages and check external consumers and archives for exact-path dependencies before release.
- Implement a deterministic EBNF-to-PEG translation or author a traceable PEG companion with a pinned parser generator. Check generated-file drift and validate each nontrivial production, including the eleven annotation body bindings and decorator rejection cases.
- Run positive and negative
.gnmfixtures through the new DSL compiler, compare ASTs or diagnostics to the chosen fixture contract, and wire that gate into spec and framework CI. Re-run the published dependency graph and site preview from immutable destination artifacts before normative release.