gnomonlearn
Docs/Gnomon DSL and graph-module format boundary

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.

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

  1. 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.
  2. 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.
  3. 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.
  4. Run positive and negative .gnm fixtures 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.