gnomonlearn
Docs/Canonical term-definition proposal

Canonical term-definition 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: proposed for owner review, 2026-10-02. No normative definition is changed by this document. The current full local Bazel suite has one failure: //kg/java/lint:lint_pr_gate reports 11 repeated names with different definitions. TERM_DRIFT_GAPS.md inventories the source pairs.

Give each concept one canonical glossary definition, and put narrower syntax, examples, and constraints in its owning RFC section. A term name must not be used for two concepts. Keep the exact-definition drift gate; do not create an exception list. The seven pairs below can share the RFC-0000 definition while their RFC-specific details remain in prose and normative rules:

TermDetailed ownerDetail retained outside the repeated definition
AspectRFC-0004Selectors, merge modes, and cross-cutting cardinality
KindRFC-0036Resource string labels and the ltree convention
ModuleRFC-0040Versioned graph contribution and (namespace, version) identity
Presentation facetRFC-0004.gnm syntax and the no-structure constraint
PrincipalRFC-0048Caller examples and stable runtime identity
Semantic facetRFC-0004.gnm declaration, includes, rules, and AI permissions
ViewRFC-0003Layer 0 entity and scope syntax

Four names need an explicit contract decision before their Lean term records and generated catalogs change:

TermRecommended decisionConsequence to review
CommandReserve Command for the submitted runtime request in RFC-0010. Use action declaration for the authoring form. RFC-0006 §4.4 already says an action compiles to a kernel reducer and its submitted instance becomes a Command. Remove RFC-0000’s claim that the two words are synonyms.Search composition, LSP, runtime API, and diagnostic prose for places where command means a declaration. Keep any wire message name Command only for the request, or document a compatibility alias.
FacetKeep Facet as the collective category in RFC-0000 and call RFC-0006’s reusable meaning module a Semantic facet, matching RFC-0004.Review RFC-0006’s facet syntax and every unqualified reference so the category and declaration are not conflated. The source keyword can remain facet; the conceptual term is qualified.
Install planDefine one plan as a deterministic, ordered build artifact of typed operations computed from the declared-versus-installed state diff. RFC-0005 owns generation and apply semantics; RFC-0041 owns module ordering and linking.Verify that artifact generation, ordering, and apply all consume the same plan identity. Avoid treating the diff and its serialized artifact as separate plans unless the implementation actually exposes both.
QueryMake RFC-0049 §11’s typed, side-effect-free projection declaration the canonical authoring form. It lowers to an RFC-0043 query operation. A compute remains a pure Schema helper, not a required query body.RFC-0000 currently says queries compose compute declarations, while RFC-0008 §8.15 allows a block with only input and returns and omits projection. Align that grammar, compiler behavior, diagnostics, reference catalogs, and examples before calling this contract resolved.

The Query recommendation makes the newer projection contract the one compiler path. An alternative is to support both compute composition and projection bodies; that requires two explicit grammar productions, lowering rules, and compatibility tests. It should not emerge accidentally from overlapping RFC definitions.

Acceptance and migration

  1. Approve or revise the four contract decisions and the shared-definition policy above. Record the decision in the relevant companion Q&A files.
  2. Edit authored RFC prose and Lean term records together. For the seven compatible pairs, preserve their detail in sections and normative statements; changing only the term string is insufficient.
  3. Regenerate all affected Markdown reference catalogs and RFC Turtle from Lean. Compare term semantics and the RDF graph with the prior preview; term nodes are blank nodes today, but downstream consumers may still use their names and definitions.
  4. Run corpus links, Lean corpus generation, portable semantic consistency, Jena lint, and the full standalone Bazel suite. Require zero term-drift rows. Run the framework KG consumers against a source-bound preview and advance the site pin only after its build and route checks pass.
  5. Keep the normative release gate red for the independent proof, projection, and Q&A blockers; zero term drift alone is not a normative release.