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.
Recommended model
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:
| Term | Detailed owner | Detail retained outside the repeated definition |
|---|---|---|
| Aspect | RFC-0004 | Selectors, merge modes, and cross-cutting cardinality |
| Kind | RFC-0036 | Resource string labels and the ltree convention |
| Module | RFC-0040 | Versioned graph contribution and (namespace, version) identity |
| Presentation facet | RFC-0004 | .gnm syntax and the no-structure constraint |
| Principal | RFC-0048 | Caller examples and stable runtime identity |
| Semantic facet | RFC-0004 | .gnm declaration, includes, rules, and AI permissions |
| View | RFC-0003 | Layer 0 entity and scope syntax |
Four names need an explicit contract decision before their Lean term records and generated catalogs change:
| Term | Recommended decision | Consequence to review |
|---|---|---|
| Command | Reserve 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. |
| Facet | Keep 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 plan | Define 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. |
| Query | Make 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
- Approve or revise the four contract decisions and the shared-definition policy above. Record the decision in the relevant companion Q&A files.
- 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.
- 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.
- 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.
- Keep the normative release gate red for the independent proof, projection, and Q&A blockers; zero term drift alone is not a normative release.