gnomonlearn
Docs/RFC-0018 compiler API domain proposal

RFC-0018 compiler API domain proposal

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-bound domain review and first-release class proposal, 2026-10-04. Owners: Compiler, DX, and Spec. No Gnomon compiler is deployed; this is a prepublication RDF correction, not a migration of stored data.

Source boundary

RFC-0018 defines the compiler session library, a mechanically derived property registry, a rule compiler service/cache, an optional debug RPC, in-process methods, and compiler API types. These are implementation and tooling concepts. They are not named .gnm declarations, Gnomon operation algebra kinds, Gnomon authoring Values, or a Gnomon application module.

The current ontology explicitly defines NamedDeclaration as an instance of a source declaration, Operation as an operation algebra kind, DataType as a primitive or named Gnomon Value type, and Module as a Gnomon module. Of RFC-0018’s 69 domain nodes, its 14 invariant summaries match the authored RFC and Lean catalog. The other 55 use the wrong class: five compiler components/artifacts as NamedDeclaration, 25 compiler and debug RPC methods as Operation, 24 compiler API shapes as DataType, and the gnomon-compiler crate as Module. The descriptions largely identify the right concepts; the RDF class claims are the mismatch. The source-bound ledger records a verdict for each node.

Proposed class map

Add compiler-specific classes under DomainEntity:

ConceptProposed classExisting node family
Compiler session, rule compiler service, debug daemonCompilerServiceFive declaration/ nodes, except the registry/cache artifacts
Derived property registry and on-disk rule cacheCompilerArtifactRemaining two declaration/ nodes
In-process CompilerSession methodsCompilerMethodoperation/CompilerSession.*
Optional JSON-RPC debug methodsCompilerRpcMethodoperation/gnomon.*
Compiler API structures/enumsCompilerApiType24 type/ nodes
Rust compiler library crateCompilerCratemodule/gnomon-compiler

Keep the current subject IRIs for the first release and change only their rdf:type triples. The path segments are identifiers, not automatic class assertions, but document the retained legacy-looking paths and publish an IRI map if a later canonical move is warranted. Do not conflate the debug RPC’s request/response DTOs with in-process types: a cross-process contract needs versioned protobuf messages unless a separately standardized schema layer owns that boundary. RFC-0018’s current JSON-RPC prose has method names but no versioned wire schema.

Q&A integration gap

The per-RFC Q&A has three resolved additions absent from the authored contract: TypeInfo.accessible_fields merge status for aspect fields, CompilerSession.validate_expr, and a read-only MCP subset of the debug RPC. They need normative prose, Lean records, API types, diagnostics, and tests before the Q&A can be treated as implemented. The Q&A’s listed MCP methods (get_type_info, validate_expr, get_diagnostics, list_declarations) also differ from §12’s existing JSON-RPC names. Define one explicit mapping and authorization/read-only boundary. A Gnomon compiler implementation is not present in the current framework checkout, so this review cannot verify runtime behavior.

Acceptance

  1. Add the compiler classes to the ontology, retype the 55 nodes in protobuf projection sources, regenerate Turtle, and compare the exact triple diff. Check claim queries and all local RDF consumers before publication.
  2. Preserve the 14 matching invariant subjects and their source-bound verdicts. Re-review changed nodes against RFC-0018 and Lean after any source or ontology edit, and update the review hashes.
  3. Integrate the three Q&A decisions into RFC-0018’s normative sections and Lean catalog; define the optional MCP/JSON-RPC wire contract and test the validate_expr/merge-status behavior when compiler code exists.
  4. Run the corpus, projection, RDF link, claim-query, and release gates. A source-aligned RDF class does not establish compiler implementation conformance.